Melhores práticas para o rastreio customizado

Para melhor monitorar, aprender e alertar sobre seus aplicativos e infraestrutura, a Instana executa processamento avançado e análise em todos os dados recebidos. Isso inclui todos os períodos recebidos de todas as origens.

Para obter o maior benefício da análise e do processamento automáticos da Instana, a inclusão de tags apropriadas em seus períodos permite que a Instana analise e aja melhor com os períodos recebidos.

Por exemplo, o código a seguir Python OpenTracing fornece menos informações.

import opentracing

with opentracing.tracer.start_active_span('vanilla') as pscope:
  # ...
  # do something that takes 50ms
  # ...
  pscope.span.log_kv({"foo": "bar"})
 

A partir deste código, só sabemos que é uma amplitude denominada vanilla que levou 50 ms de tempo. Não sabemos qual era o tipo de período: HTTP, RPC ou um período de sistema de mensagens. Não sabemos o que aconteceu durante esse tempo, como a comunicação com qualquer outro componente em sua infraestrutura.

Ao fornecer tags contextuais apropriadas do OpenTracing, a Instana analisa e extrai informações desse período para agir com base nelas.

import opentracing
import opentracing.ext.tags as ext

with opentracing.tracer.start_active_span('webserver') as pscope:
    pscope.span.set_tag(ext.SPAN_KIND, "entry")
    pscope.span.set_tag(ext.PEER_HOSTNAME, "localhost")
    pscope.span.set_tag(ext.HTTP_URL, "/python/simple/two")
    pscope.span.set_tag(ext.HTTP_METHOD, "POST")
    pscope.span.log_kv({"foo": "bar"})

    # ...
    # work that took 50ms
    # ...

    pscope.span.set_tag(ext.HTTP_STATUS_CODE, 204)
 

Esse período bem anotado informa à Instana muito mais sobre o que aconteceu no contexto do período. Nas tags fornecidas, sabemos que se trata de uma solicitação de servidor da web recebida para /python/simple/two e que o código de status HTTP resultante é 204.

Um trecho bem anotado, como o trecho anterior, permite que o Instana extraia serviços, monitore conexões e seu estado de integridade, o que proporciona uma experiência mais rica no seu painel.

Para obter detalhes sobre este exemplo, consulte a especificação OpenTracing, que define a lista oficial de todas as tags OpenTracing compatíveis. Uma lista abrangente de tags suportadas pela Instana (que é um superconjunto de tags do OpenTracing) está disponível no final desta página.

Dentro do rastreio distribuído, há três grandes tipos de spans:

• Entrada: anota a recepção de uma solicitação, o início de uma nova tarefa ou o consumo de uma mensagem
• Intermediário: Annotates trabalho interno que não faz ou recebe chamadas (por exemplo, visualização de visualização)
• Exit: Annotates trabalho que faz uma chamada para um serviço remoto ou publica uma mensagem para uma fila

A tag span.kind marca o tipo de span que está sendo relatado. Consulte span.kind a tabela no final desta página ou, em alternativa, a especificação do OpenTracing para obter mais detalhes.

Ao iniciar novos rastreios, comece com um período Entrada. Se você não especificar a tag span.kind, o período será considerado do tipo Entrada. Configurar essa tag com o valor apropriado permite um melhor processamento, extração de chamada de back-end de visualização e mapeamento na Instana.

Consulte o exemplo de Go a seguir:

// Start a new entry span and set 'kind' to Consumer (entry)
entrySpan := ot.StartSpan("RPCJobRunner")
entrySpan.SetTag(string(ext.SpanKind), string(ext.SpanKindConsumerEnum))

// Now the RPC exit span
spanName := fmt.Sprintf("%s %s", request.Service, request.Method)
clientSpan := ot.StartSpan(spanName, ot.ChildOf(entrySpan.Context()))
clientSpan.SetTag(string(ext.SpanKind), string(ext.SpanKindRPCClientEnum))
clientSpan.SetTag("rpc.call", request.Method)

// Make the RPC call

clientSpan.Finish()
entrySpan.Finish()
 

Os períodos que representam trabalho que continha um erro, como uma exceção, devem incluir as tags error e message. Para definições dessas tags, veja a definição na tabela da seguinte forma.

Para transmitir contexto além dos limites como hosts, filas e serviços, o rastreio distribuído inclui um método. Isso é feito geralmente com transportadores, como cabeçalhos de HTTP ou cabeçalhos da fila de mensagens.

Para obter mais detalhes, consulte a nossa documentação sobre HTTP Headers.

Isto é opcional. Nomes de serviço são aqueles aplicados a processos de aplicativo monitorado. Em muitas linguagens, o melhor nome de serviço pode ser detectado automaticamente com base na Estrutura em uso ou na linha de comandos do processo.

Se você quiser substituir isso, configure um nome de serviço por Rastreador. Consulte o exemplo a seguir para a linguagem Go.

serviceName := "default"
if *isServer {
    serviceName = "rpc-client"
} else {
    serviceName = "rpc-server"
}

opts := instana.Options{Service: serviceName})
opentracing.InitGlobalTracer(instana.NewTracerWithOptions(&opts)
 

Todos os rastreadores do OpenTracing da Instana também suportam essa configuração por meio de variável de ambiente. Se você configurar a variável de ambiente INSTANA_SERVICE_NAME para o processo, o valor será usado como nome de serviço para o processo. Isso substitui qualquer configuração de nome do serviço no nível de código.

Consulte também a documentação sobre as técnicas e regras gerais de extração de serviços do Instana.

Isto é opcional. Em muitas linguagens, os nomes de terminais e de chamadas são detectados automaticamente com base no tipo de serviço.

Se você quiser substituir isso, configure os nomes de terminais e de chamadas por Rastreador. Consulte o exemplo a seguir para a linguagem Java.

SpanSupport.annotate(Span.Type.ENTRY, "my-custom-span", "endpoint", "endpoint-name");
SpanSupport.annotate(Span.Type.ENTRY, "my-custom-span", "call.name", "call-name");
 

Para obter mais informações sobre as técnicas e regras gerais de extração de terminais do Instana, consulte nossa documentação sobre terminais.

O SDK de rastreio calcula automaticamente a duração do span desde o início e o término do span.

Geralmente representa o que você deseja medir, no entanto, quando ele não o faz, é possível sobrescrevê-lo usando a tag duration.

O formato esperado está em milissegundos.

// Overwrite the span duration with 15 milliseconds.
SpanSupport.annotate(Span.Type.ENTRY, "my-custom-span", "duration", "15");
 

A Instana suporta agrupamento automático de terminais com modelos de caminho. Isso é suportado prontamente com o rastreio da Instana para muitas estruturas. No caso do ` OpenTracing, `, é necessário um passo adicional, conforme descrito a seguir.

Várias estruturas geralmente têm um padrão de caminho de REST semelhante ao seguinte:

/api/query/1956-01-31/Guido-van-Rossum
/api/query/1976-04-18/Andrew-Ng
/api/query/1912-06-23/Alan-Turing
 

Esses pontos de extremidade semelhantes podem ser agrupados informando uma http.path_tpl chave com o valor em seus intervalos do HTTP/api/query/{birthdate}/{name}; o Instana usa esse modelo para agrupar automaticamente os pontos de extremidade que correspondem ao padrão fornecido. No painel do Instana, os pontos de extremidade HTTP serão agrupados como um único ponto de extremidade:

/api/query/{birthdate}/{name}
 

Consulte a seguir um exemplo de Go:

span := ot.GlobalTracer().StartSpan("myTemplatedSpan", ext.RPCServerOption(incomingContext))
span.SetTag("http.path_tpl", "/api/query/{birthdate}/{name}")
span.SetTag(string(ext.SpanKind), string(ext.SpanKindRPCServerEnum))
span.SetTag(string(ext.HTTPUrl), req.URL.Path)
span.SetTag(string(ext.HTTPMethod), req.Method)
span.SetTag(string(ext.HTTPStatusCode), 200)
 

Observe que esse recurso é específico da Instana e não compatível com o OpenTracing.

Esta seção lista as tags específicas que a Instana procura ao identificar e processar períodos. Quando um subconjunto das tags a seguir é encontrado para um span, o Instana pode processar, analisar, visualizar e emitir alertas sobre os spans recebidos com maior eficácia.

Observe que as tags listadas a seguir são um superconjunto das tags OpenTracing padrão. Cada tag é marcada se ela é OpenTracing compatível com um ✓ ou x se não for.

Algumas descrições de tags a seguir foram extraídas diretamente do documento de convenções semânticas do OpenTracing.

• OpenTracing documentos

• OpenCensus documentos