Configurando rastreadores usando o arquivo de configuração do agente

Você pode definir configurações específicas do tracer usando o arquivo de configuração do agente (instanaAgentDir/etc/instana/configuration.yaml) caso o agente esteja instalado em um host. Essas configurações controlam como os rastreadores do ` Instana ` capturam e processam os dados de rastreamento nas suas aplicações monitoradas.

Para obter uma lista detalhada de todos os parâmetros de configuração do ` Instana `, consulte InstanaHelm chart.

Para implantações do ` Instana ` no ` Kubernetes `, consulte a seção “Configurando o agente do ` Kubernetes ` usando o arquivo de configuração ”.

Para opções gerais de configuração do agente, consulte “Configurando agentes de host usando o arquivo de configuração do agente ”.

Nota:
O formato do arquivo de configuração do agente é YAML, que diferencia entre espaços em branco e caracteres de espaço. Portanto, certifique-se de não usar espaços desnecessários no arquivo. Para criar um recuo, use apenas dois espaços em branco.

Captura de cabeçalhos personalizados do ` HTTP `

Por padrão, o ` Instana ` não coleta cabeçalhos ` HTTP ` ao rastrear chamadas ` HTTP `.

Se necessário, você pode ativar esse recurso aplicando a seguinte configuração no arquivo de configuração do agente:

com.instana.tracing:
  extra-http-headers:
    - 'x-request-id'
    - 'x-loadtest-id'
    - ...

Os valores não fazem distinção entre maiúsculas e minúsculas. Os cabeçalhos coletados são exibidos nos detalhes da chamada (na seção " Detalhes da chamada"). Você também pode usar os nomes dos cabeçalhos e seus valores para pesquisar chamadas e rastreamentos (na interface do usuário ou por meio do API ) e para a configuração do serviço.

Atualmente, esse recurso apresenta as seguintes restrições:

  • Todos os rastreadores capturam os cabeçalhos das solicitações nas entradas do tipo “HTTP ” (chamadas do tipo “ HTTP ” recebidas pelo processo instrumentado).
  • Alguns rastreadores podem capturar cabeçalhos de resposta em entradas do tipo “ HTTP ”. Para mais informações, consulte a Tabela 1.
  • Alguns rastreadores podem capturar cabeçalhos de solicitação e resposta em saídas do tipo “ HTTP ” (chamadas de HTTP em que o processo instrumentado é o cliente). Para mais informações, consulte a Tabela 1.
  • Se o mesmo cabeçalho estiver presente como um cabeçalho de solicitação e um cabeçalho de resposta, um dos dois valores talvez não seja capturado pelo rastreador.
Tabela 1. Informações dos cabeçalhos de solicitação e resposta do Tracer
Rastreador Cabeçalhos de solicitação em entradas HTTP Cabeçalhos de resposta em entradas HTTP Cabeçalhos de solicitação em saídas HTTP Cabeçalhos de resposta em saídas HTTP
Go ✅ ✅ ✅ ✅
Java ✅ ✅1 ❌ ❌
.NET ✅ ✅ ✅ ✅
Node.js ✅ ✅ ✅ ✅
PHP ✅ ❌ ❌ ❌
NGINX ✅ ❌ — —
Python ✅ ✅ ✅ ✅
Ruby ✅ ✅ ✅ ✅
HTTPd ✅ ❌ — —

Configurando cabeçalhos de correlação de rastreamento d Kafka

É possível configurar o formato dos cabeçalhos de correlação de rastreamento d Kafka, utilizados pelos rastreadores d Instana, por meio da configuração com.instana.tracing.kafka.header-format. Os valores válidos são binary, string, ou both. Consulte o seguinte exemplo:

com.instana.tracing:
  kafka:
    header-format: string # possible values: binary, both, string

Não se deve desativar totalmente a correlação de rastreamento do ` Kafka `. No entanto, se você precisar desativar completamente a correlação de rastreamento do ` Kafka `, defina com.instana.tracing.kafka.trace-correlation: false. Consulte o seguinte exemplo:

com.instana.tracing:
  kafka:
    trace-correlation: false
Nota:
Muitos conectores do Kafka utilizam SimpleHeaderConverter como mecanismo padrão para lidar com cabeçalhos de mensagens do Kafka. Este conversor pode apresentar falhas ao processar cabeçalhos de rastreamento do tipo “ Instana ”, pois tenta deserializar os valores dos cabeçalhos em tipos nativos, o que pode causar erros de estouro numérico. Para resolver esse problema, configure o ` Kafka Connect ` para usar StringConverter:
header.converter=org.apache.kafka.connect.storage.StringConverter

Para obter mais informações, consulte Migração de cabeçalho Kafka.

Desativando o rastreamento

Você pode desativar o rastreamento para um tipo específico de intervalo (frameworks, bibliotecas ou instrumentações) ou para grupos inteiros de bibliotecas (categoria de intervalo). Por exemplo, para excluir totalmente o redis pacote do rastreamento ou desativar o rastreamento para todas as bibliotecas relacionadas a registros, use a disable opção de configuração.

Nota:
Esse recurso ainda não é compatível com todos os rastreadores.

Para definir essa configuração, especifique os tipos ou categorias que você deseja desativar na com.instana.tracing.disable seção do seu arquivo de configuração do agente, conforme mostrado no exemplo a seguir:

com.instana.tracing:
  disable:
    redis: true         # Disable Redis
    console: false      # Keep console enabled
    logging: true       # Disable the entire logging category

em que:

  • true: Desativa o rastreamento para o tipo ou categoria especificados.
  • false: Mantém explicitamente o tipo ou a categoria especificada ativada.

No exemplo anterior, a configuração desativa todas as instrumentações dentro da logging categoria, exceto console, que está explicitamente ativada. Além disso, a configuração também exclui todos redis os intervalos relacionados do rastreamento. Não são coletados nem relatados intervalos para bibliotecas ou categorias desativadas.

Informações de suporte

A tabela a seguir lista os rastreadores que permitem desativar os rastros:

Tabela 2. Tracers que permitem desativar os rastros
Rastreador Suporta a desativação de rastreamentos
Node.js ✅
Go ❌
Java ✅
Python ✅
Ruby ❌
PHP ✅
.Net ❌
NGINX ❌

Desativando o recurso “ W3C ”

Por padrão, os rastreadores do Instana processam e propagam os cabeçalhos tracestate W3C traceparent e para a correlação de rastreamentos distribuídos. É possível desativar a correlação, a propagação ou ambas as funções d W3C, de forma independente, por meio do arquivo de configuração do agente.

Desativando a correlação “ W3C ”

Desativa o processamento de cabeçalhos tracestate W3C ou traceparent recebidos, sem afetar a propagação das mensagens enviadas.

com.instana.tracing:
  global:
    disable-w3c-correlation: true

Desativando a propagação de “ W3C ”

Desativa a inserção de W3C traceparent/tracestate cabeçalhos nas solicitações enviadas.

com.instana.tracing:
  global:
    disable-w3c-propagation: true

Desativando completamente o ` W3C `

Desativa tanto a correlação quanto a propagação do ` W3C `.

com.instana.tracing:
  global:
    disable-w3c: true

Informações de suporte

A tabela a seguir lista os traçadores que permitem desativar a função “ W3C ” por meio da configuração do agente:

Tabela 3. Tracers que permitem desativar o recurso “ W3C ” por meio da configuração do agente
Rastreador Suportado
Node.js ✅
Go ❌
Java ❌
Python ❌
Ruby ❌
PHP ❌
.NET ❌
NGINX ❌

Capturando rastreios de pilha

Você pode configurar a captura do rastreamento de pilha para intervalos de saída em todos os seus serviços. Por padrão, os rastreadores capturam os últimos 10 pontos de chamada para cada intervalo de saída capturado.

Nota:
  • Esse recurso ainda não é compatível com todos os rastreadores.
  • Os rastreamentos de pilha dos intervalos de entrada de ` HTTP ` normalmente não são coletados, pois mostram apenas o código do framework ou do núcleo do tempo de execução.

Você pode configurar dois aspectos da captura do rastreamento da pilha:

  • Comprimento do rastreamento de pilha : o número de pontos de chamada a serem capturados.
    • Valores permitidos: 0–500
    • Valor padrão: 10
  • Modo de rastreamento de pilha : como os rastreamentos de pilha são capturados.
    • Valores suportados:
      • all: Coleta o rastreamento da pilha para todos os intervalos de saída (padrão).
      • error: Recolhe o rastreamento da pilha apenas para os intervalos com erros.
      • none: Não coleta o rastreamento da pilha.

Para configurar a captura do rastreamento de pilha, defina os parâmetros na com.instana.tracing.global seção do seu arquivo de configuração do agente, conforme mostrado no exemplo a seguir:

com.instana.tracing:
  global:
    stack-trace-length: 15
    stack-trace: 'error'

No exemplo anterior, a configuração define a profundidade do rastreamento de pilha para 15 pontos de chamada em todos os intervalos de saída e utiliza o error modo.

Informações de suporte

A tabela a seguir lista os rastreadores que permitem configurar a captura de rastreamento de pilha por meio da configuração do agente:

Tabela 4. Tracers que suportam a configuração do rastreamento de pilha
Rastreador Suporta a configuração do rastreamento de pilha Versão mínima do Tracer ou do Collector
Node.js ✅ Instana Node.js 5.2.0 e modelos posteriores
Go ❌ —
Java ✅ Instana Java Tracer 2.0.20 e versões posteriores
Python ✅ Instana Python pacote/sensor 3.10.0 e versões posteriores
Ruby ✅ Instana Ruby gem/sensor 2.5.0 e versões posteriores
PHP ✅ Instana PHP Tracer 5.9.0 e versões posteriores
.Net ❌ —
NGINX ❌ —

Ignorando pontos finais

Você pode excluir pontos finais específicos do rastreamento. Por exemplo, se você estiver usando o redis pacote e quiser evitar o rastreamento de comandos, como GET, TYPE, ou outros, pode usar a ignore-endpoints opção de configuração.

Nota:
Atualmente, o recurso “Ignorar pontos finais” apresenta as seguintes restrições:
  • Apenas determinados pacotes são compatíveis.
  • Nem todos os traçadores são compatíveis.

Para obter mais informações sobre os pacotes e rastreadores específicos que oferecem suporte a esse recurso, consulte a seção “Informações de suporte ”.

Opções de Filtragem

Você pode filtrar os traços usando as seguintes opções:

  • Filtragem por nome do método: com essa opção, você pode filtrar os traços com base apenas nos nomes dos métodos. Isso é útil quando se deseja ignorar operações específicas, como GET chamadas em Redis ou QUERY chamadas em DynamoDB.
  • Filtragem por nome do método e endpoint: com essa opção, é possível excluir rastreamentos com base tanto no método quanto em endpoints específicos. topic2consumeEssa opção é especialmente útil para tecnologias como Kafka[nome da tecnologia], nas quais é possível excluir rastreamentos de um método específico (por exemplo, [nome do método]), mas apenas para determinados tópicos (por exemplo, [tópico] topic1 ou [tópico]).

Regras de filtragem

As regras para filtrar traços são as seguintes:

  • Quando um rastreamento é ignorado, todos os rastreamentos subsequentes a jusante também são ignorados.
  • Use * para ignorar todos os endpoints ou métodos.
  • Os valores de ponto final (como nomes de tópicos d Kafka ) permanecem consistentes entre os serviços.
  • Os nomes dos métodos podem variar dependendo da linguagem de programação e da tecnologia. Para determinar o método e o ponto final corretos para o seu serviço, consulte a interface do usuário do Instana.

A captura de tela a seguir da interface do usuário do Instana fornece uma referência visual para identificar o método e o endpoint corretos para a configuração:

Figura 1. Métodos e parâmetros de avaliação na interface do usuário
Instana Captura de tela da interface do usuário mostrando a configuração de métodos e endpoints

Configurando pontos de extremidade a serem excluídos

Nota:
Quando seu sistema utiliza vários serviços em diferentes linguagens de programação, certifique-se de que todos os nomes de métodos necessários estejam incluídos no arquivo de configuração do agente, pois eles podem variar de uma linguagem para outra.

Para configurar os endpoints a serem ignorados, especifique os endpoints que devem ser excluídos do monitoramento na com.instana.tracing.ignore-endpoints seção do seu arquivo de configuração do agente, conforme mostrado no exemplo a seguir:

com.instana.tracing:
  ignore-endpoints:

    # Filtering by Method Name
    redis:
      - 'get'
      - 'type'
    dynamodb:
      - 'query'
    kafka:
      - 'send'

    # Filtering by Method Name and Endpoint for Kafka
    kafka:
      - methods: ["consume"]
        endpoints: ["topic1", "topic2"]  # Exclude consume calls for topic1 and topic2

      - methods: ["consume", "send"]
        endpoints: ["topic3"]  # Exclude both consume and send calls for topic3

      - methods: ["*"]
        endpoints: ["topic4"]  # Exclude all methods for topic4

      - methods: ["consume"]
        endpoints: ["*"]  # Exclude consume method for all topics

No exemplo anterior, os seguintes registros são ignorados para as opções de filtragem listadas:

  • Filtrar por método (Redis, DynamoDB, e Kafka)
    • GET e TYPE comandos em Redis
    • QUERY comando em DynamoDB
    • SEND método em Kafka e todos os rastros a jusante
  • Filtrar por método e parâmetro (Kafka apenas)
    • CONSUME método para topic1 e topic2 em Kafka e todos os traços a jusante
    • CONSUME e SEND métodos para topic3 em Kafka todos os rastros posteriores
    • Todos os métodos (*) para topic4 em Kafka e todos os rastros a jusante
    • CONSUME método para todos os tópicos (*) e todos os rastros a jusante

Informações de suporte

A tabela a seguir lista os rastreadores e pacotes que oferecem suporte à opção de ignorar pontos finais:

Tabela 5. Tracers e pacotes que permitem ignorar pontos finais
Pacotes Suportados Node.js Java Go PHP Python Ruby .NET NGINX
Redis ✅ ✅ ❌ ❌ ✅ ❌ ❌ ❌
DynamoDB ✅ ✅ ❌ ❌ ✅ ❌ ❌ ❌
Kafka ✅ ✅ ❌ ❌ ✅ ❌ ❌ ❌
HTTP ✅ ❌ ❌ ❌ ❌ ❌ ❌ ❌
Nota:
No caso do Node.js, a filtragem do HTTP se aplica apenas às solicitações recebidas (de entrada). As chamadas de saída ( HTTP ) não podem ser filtradas.

HTTP 4xx relatórios de erros de código de status

Por padrão, o Instana não considera as respostas HTTP 4xx como erros nas chamadas HTTP. Você pode ativar esse comportamento para monitorar erros do cliente, como respostas 403 Forbidden repetidas ou 401 Unauthorized .

Nota:
  • Essa configuração se aplica apenas às chamadas de saída ( HTTP ). As chamadas recebidas (de entrada) do tipo “ HTTP ” nunca são marcadas como erros com base nos códigos de resposta “ 4xx ”, independentemente dessa configuração.
  • Nem todos os traçadores são compatíveis.

com.instana.tracing.http.exitAs seguintes opções de configuração estão disponíveis em:

  • classify-all-4xx-as-errors: Relata todas as respostas do tipo “ 4xx ” como erros.
  • classify-as-errors: Relata como erros apenas os códigos de status especificados em 4xx.

Quando ambas as opções estiverem definidas, classify-as-errors tem precedência, e somente os códigos listados são tratados como erros. Os códigos de status para classify-as-errors devem estar no intervalo 400–499. Quaisquer códigos fora desse intervalo são ignorados.

Classificar todas as respostas do tipo “ 4xx ” como erros

Para tratar todas as respostas do tipo “ 4xx ” em uma chamada de saída como um erro, adicione o seguinte ao seu arquivo de configuração do agente:

com.instana.tracing:
  http:
    exit:
      classify-all-4xx-as-errors: true

Classificar respostas específicas do ` 4xx ` como erros

classify-as-errorsPara tratar apenas determinados códigos de status como erros, liste-os em:

com.instana.tracing:
  http:
    exit:
      classify-as-errors:
        - 401
        - 403

Informações de suporte

A tabela a seguir lista os traçadores que oferecem suporte ao relatório de erros por meio do código de status HTTP 4xx :

Tabela 6. Tracers que oferecem suporte à geração de relatórios de erros com códigos de status do tipo “ HTTP ” e “ 4xx ”
Rastreador Suportado
Node.js ✅
Go ❌
Java ❌
Python ❌
Ruby ❌
PHP ✅
.NET ❌
NGINX ❌
1 As tecnologias compatíveis incluem Servlet, Spring, Tomcat, e http4s.