Share via

Processadores de telemetria (versão prévia) – Application Insights do Azure Monitor para Java

  • Artigo

Observação

O recurso de processadores de telemetria é designado como versão prévia porque não podemos garantir a compatibilidade com versões anteriores da versão para a versão devido ao estado experimental das convenções semânticas de atributo. No entanto, o recurso foi testado e tem suporte na produção.

O Java 3.x para Application Insights pode processar dados de telemetria antes de os dados serem exportados.

Alguns casos de uso:

  • Mascare dados confidenciais.
  • Adicione dimensões personalizadas condicionalmente.
  • Atualize o nome do span, que é usado para agregar telemetria semelhante no portal do Azure.
  • Descartar atributos de span específicos para controlar os custos de ingestão.
  • Filtre algumas métricas para controlar os custos de ingestão.

Observação

Se você pretende descartar spans (inteiros) específicos para controlar o custo de ingestão, confira substituições de amostragem.

Terminologia

Antes de saber mais sobre os processadores de telemetria, você deve entender os termos span e log.

Um span é um tipo de telemetria que representa um dos seguintes:

  • Uma solicitação de entrada.
  • Uma dependência de saída (por exemplo, uma chamada remota para outro serviço).
  • Uma dependência em processo (por exemplo, trabalho sendo feito por subcomponentes do serviço).

Um log é um tipo de telemetria que representa:

  • dados de log capturados do Log4J, Logback e java.util.logging

Para processadores de telemetria, os seguintes componentes de span/log são importantes:

  • Nome
  • Corpo
  • Atributos

O nome do span é a exibição primária para solicitações e dependências no portal do Azure. Atributos de span representam propriedades padrão e personalizadas de uma determinada solicitação ou dependência.

A mensagem de rastreamento ou o corpo é a exibição principal para logs no portal do Azure. Atributos de log representam propriedades padrão e personalizadas de um determinado log.

Tipos de processador de telemetria

Atualmente, os quatro tipos de processadores de telemetria são

  • Processadores de atributo
  • Processadores de intervalo
  • Processadores de log
  • Filtros de métricas

Um processador de atributos pode inserir, atualizar, excluir ou aplicar hash em atributos de um item de telemetria (span ou log). Ele também pode usar uma expressão regular para extrair um ou mais atributos novos de um atributo existente.

Um processador de span pode atualizar o nome da telemetria de solicitações e dependências. Ele também pode usar uma expressão regular para extrair um ou mais atributos novos do nome do span.

Um processador de log pode atualizar o nome da telemetria dos logs. Ele também pode usar uma expressão regular para extrair um ou mais atributos novos do nome do log.

Um filtro de métrica pode filtrar as métricas para ajudar a controlar o custo de ingestão.

Observação

Atualmente, os processadores de telemetria processam apenas atributos do tipo cadeia de caracteres. Eles não processam atributos do tipo booliano ou número.

Introdução

Para começar, crie um arquivo de configuração chamado applicationinsights.jsem. Salve-o no mesmo diretório que applicationinsights-agent-*.jar. Use o modelo a seguir.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        ...
      },
      {
        "type": "attribute",
        ...
      },
      {
        "type": "span",
        ...
      },
      {
        "type": "log",
        ...
      },
      {
        "type": "metric-filter",
        ...
      }
    ]
  }
}

Processador de atributos

O processador de atributos muda os atributos de um span ou um log. Ele pode permitir incluir ou excluir span ou log. Ele usa uma lista de ações que são executadas na ordem em que o arquivo de configuração especifica. O processador permite estas ações:

  • insert
  • update
  • delete
  • hash
  • extract
  • mask

insert

A ação insert insere um novo atributo no item de telemetria em que a key ainda não exista.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "value": "value1",
        "action": "insert"
      }
    ]
  }
]

A ação insert requer as seguintes configurações:

  • key
  • value ou fromAttribute
  • action: insert

update

A ação update atualiza um atributo no item de telemetria onde o key já exista.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "value": "newValue",
        "action": "update"
      }
    ]
  }
]

A ação update requer as seguintes configurações:

  • key
  • value ou fromAttribute
  • action: update

delete

A ação delete exclui um atributo de um item de telemetria.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "action": "delete"
      }
    ]
  }
]

A ação delete requer as seguintes configurações:

  • key
  • action: delete

hash

A ação hash cria um hash (SHA1) de um valor de atributo existente.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "action": "hash"
      }
    ]
  }
]

A ação hash requer as seguintes configurações:

  • key
  • action: hash

extract

Observação

O recurso extract está disponível somente na versão 3.0.2 e posterior.

A ação extract extrai valores usando uma regra de expressão regular da chave de entrada para chaves de destino que a regra especifica. Se uma chave de destino já existe, a ação extract substitui a chave de destino. Essa ação se comporta como a configuração do processador de intervalotoAttributes, em que o atributo existente é a origem.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "pattern": "<regular pattern with named matchers>",
        "action": "extract"
      }
    ]
  }
]

A ação extract requer as seguintes configurações:

  • key
  • pattern
  • action: extract

mask

Observação

O recurso mask está disponível somente na versão 3.2.5 e posterior.

A ação mask mascara valores de atributo usando uma regra de expressão regular especificada no pattern e replace.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attributeName",
        "pattern": "<regular expression pattern>",
        "replace": "<replacement value>",
        "action": "mask"
      }
    ]
  }
]

A ação mask requer as seguintes configurações:

  • key
  • pattern
  • replace
  • action: mask

pattern pode conter um grupo nomeado colocado entre ?< e >:. Exemplo: (?<userGroupName>[a-zA-Z.:\/]+)\d+? O grupo é (?<userGroupName>[a-zA-Z.:\/]+) e userGroupName é o nome do grupo. pattern pode conter o mesmo grupo nomeado colocado entre ${ e } seguido pela máscara. Exemplo em que a máscara é **: ${userGroupName}**.

Confira Exemplos do processador de telemetria para obter exemplos de mascaramento.

Critérios de inclusão e critérios de exclusão

Os processadores de atributo dão suporte aos critérios e opcionais include e exclude. Um processador de atributos é aplicado somente à telemetria que corresponde aos seus critérios include (se disponíveis) e não correspondem aos seus critérios exclude (se disponíveis).

Para configurar essa opção, em include ou exclude (ou em ambos), especifique pelo menos um matchType e um spanNames ou attributes. A configuração include ou exclude permite mais de uma condição especificada. Todas as condições especificadas devem ser avaliadas como true para resultar em uma correspondência.

  • Campos obrigatórios:

    • matchType controla como os itens em matrizes spanNames e matrizes attributes são interpretados. Os valores possíveis são regexp e strict. Correspondências de expressão regular são executadas com base no valor do atributo inteiro, portanto, se você quiser corresponder a um valor que contenha abc em qualquer lugar, use .*abc.*.

  • Campos opcionais:

    • spanNames deve corresponder a pelo menos um dos itens.
    • attributes especifica a lista de atributos a serem correspondentes. Todos esses atributos devem corresponder exatamente para resultar em uma correspondência.

Observação

Se ambos include e exclude forem especificados, as propriedades include serão verificadas antes da verificação das propriedades exclude.

Observação

Se a configuração include ou exclude ou não tiverem especificado spanNames, os critérios de correspondência serão aplicados no spans e no logs.

Amostra de uso

"processors": [
  {
    "type": "attribute",
    "include": {
      "matchType": "strict",
      "spanNames": [
        "spanA",
        "spanB"
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "redact_trace",
          "value": "false"
        }
      ]
    },
    "actions": [
      {
        "key": "credit_card",
        "action": "delete"
      },
      {
        "key": "duplicate_key",
        "action": "delete"
      }
    ]
  }
]

Para obter mais informações, confira exemplos do processador de telemetria.

Processador de span

O processador de span muda o nome do span ou os atributos de um span com base no nome do span. Ele pode permitir incluir ou excluir spans.

Dar nome a um intervalo

A seção name requer a configuração fromAttributes. Os valores desses atributos são usados para criar um novo nome, concatenado na ordem em que a configuração especifica. O processador só muda o nome do span se todos esses atributos estiverem presentes no span.

A configuração separator é opcional. Essa configuração é uma cadeia de caracteres e você pode usar valores divididos.

Observação

Se a renomeação depender do processador de atributos para mudar os atributos, verifique se o processador de span está especificado após o processador de atributos na especificação do pipeline.

"processors": [
  {
    "type": "span",
    "name": {
      "fromAttributes": [
        "attributeKey1",
        "attributeKey2",
      ],
      "separator": "::"
    }
  }
]

Extrair atributos do nome do span

A seção toAttributes lista as expressões regulares para correspondência com o nome do span. Ela extrai atributos com base em subexpressões.

A configuração rules é necessária. Essa configuração lista as regras que são usadas para extrair valores de atributo do nome de extensão.

Os nomes de atributos extraídos substituem os valores no nome do span. Cada regra na lista é uma cadeia de caracteres de padrão de expressão regular (regex).

Veja como os nomes de atributos extraídos substituem valores:

  1. O nome do span é verificado em relação ao regex.
  2. Se o regex corresponder, todas as subexpressões nomeadas do regex serão extraídas como atributos.
  3. Os atributos extraídos são adicionados ao span.
  4. Cada nome de subexpressão se torna um nome de atributo.
  5. A parte correspondente da subexpressão se torna o valor do atributo.
  6. O nome do atributo extraído substitui a parte correspondente no nome do span. Se os atributos já existirem no span, eles serão substituídos.

Esse processo é repetido para todas as regras na ordem em que são especificadas. Cada regra seguinte funciona no nome do span que é a saída da regra anterior.

"processors": [
  {
    "type": "span",
    "name": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

Atributos de span comuns

Esta seção lista alguns atributos de span comuns que os processadores de telemetria podem usar.

Spans HTTP

Atributo Tipo Descrição
http.request.method (costumava ser http.method) string Método de solicitação HTTP.
url.full (intervalo de cliente) ou url.path (intervalo de servidor) (costumava ser http.url) string URL de solicitação HTTP completa no formulário scheme://host[:port]/path?query[#fragment]. O fragmento geralmente não é transmitido via HTTP. Mas, se o fragmento for conhecido, ele deverá ser incluído.
http.response.status_code (costumava ser http.status_code) número Código de status de resposta HTTP.
network.protocol.version (costumava ser http.flavor) string Tipo de protocolo HTTP.
user_agent.original (costumava ser http.user_agent) string Valor do cabeçalho do agente de usuário HTTP enviado pelo cliente.

Spans do Java Database Connectivity

A tabela a seguir descreve atributos que você pode usar em spans do Java Database Connectivity (JDBC):

Atributo Tipo Descrição
db.system string Identificador do produto do DBMS (gerenciador de banco de dados) que está sendo usado. Consulte Convenções semânticas para operações de banco de dados.
db.connection_string string A cadeia de conexão usada para se conectar ao banco de dados. Recomendamos que você remova as credenciais incorporadas.
db.user string Nome de usuário para acessar o banco de dados.
db.name string Cadeia de caracteres usada para relatar o nome do banco de dados que está sendo acessado. Para comandos que mudam o banco de dados, essa cadeia de caracteres deve ser definida para o banco de dados de destino, mesmo que o comando falhe.
db.statement string A instrução do banco de dados que está sendo executada.

Critérios de inclusão e critérios de exclusão

Os processadores de span dão suporte aos critérios e opcionais include e exclude. Um processador de span é aplicado somente à telemetria que corresponde aos seus critérios include (se disponíveis) e não correspondem aos seus critérios exclude (se disponíveis).

Para configurar essa opção, em include ou exclude (ou em ambos), especifique, pelo menos, um matchType e um spanNames ou o intervalo attributes. A configuração include ou exclude permite mais de uma condição especificada. Todas as condições especificadas devem ser avaliadas como true para resultar em uma correspondência.

  • Campos obrigatórios:

    • matchType controla como os itens em matrizes spanNames e matrizes attributes são interpretados. Os valores possíveis são regexp e strict. Correspondências de expressão regular são executadas com base no valor do atributo inteiro, portanto, se você quiser corresponder a um valor que contenha abc em qualquer lugar, use .*abc.*.

  • Campos opcionais:

    • spanNames deve corresponder a pelo menos um dos itens.
    • attributes especifica a lista de atributos a serem correspondentes. Todos esses atributos devem corresponder exatamente para resultar em uma correspondência.

Observação

Se ambos include e exclude forem especificados, as propriedades include serão verificadas antes da verificação das propriedades exclude.

Amostra de uso

"processors": [
  {
    "type": "span",
    "include": {
      "matchType": "strict",
      "spanNames": [
        "spanA",
        "spanB"
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute1",
          "value": "attributeValue1"
        }
      ]
    },
    "name": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

Para obter mais informações, confira exemplos do processador de telemetria.

Processador de log

Observação

Os processadores de log estão disponíveis a partir da versão 3.1.1.

O processador de log modifica o corpo da mensagem ou os atributos de um log com base no corpo da mensagem do log. Ele pode permitir incluir ou excluir logs.

Atualizar o corpo da mensagem do log

A seção body requer a configuração fromAttributes. Os valores desses atributos são usados para criar um novo corpo, concatenado na ordem em que a configuração especifica. O processador muda o corpo do log somente se todos esses atributos estiverem presentes no log.

A configuração separator é opcional. Essa configuração é uma cadeia de caracteres. Você pode especificá-lo para dividir valores.

Observação

Se a renomeação depender do processador de atributos para mudar os atributos, verifique se o processador de log está especificado após o processador de atributos na especificação do pipeline.

"processors": [
  {
    "type": "log",
    "body": {
      "fromAttributes": [
        "attributeKey1",
        "attributeKey2",
      ],
      "separator": "::"
    }
  }
]

Extrair atributos do corpo da mensagem de log

A seção toAttributes lista as expressões regulares para correspondência com o corpo da mensagem do log. Ela extrai atributos com base em subexpressões.

A configuração rules é necessária. Essa configuração lista as regras que são usadas para extrair valores de atributo do corpo.

Os nomes de atributos extraídos substituem os valores no corpo da mensagem do log. Cada regra na lista é uma cadeia de caracteres de padrão de expressão regular (regex).

Veja como os nomes de atributos extraídos substituem valores:

  1. O corpo da mensagem do log é verificado em relação ao regex.
  2. Se o regex corresponder, todas as subexpressões nomeadas do regex serão extraídas como atributos.
  3. Os atributos extraídos são adicionados ao log.
  4. Cada nome de subexpressão se torna um nome de atributo.
  5. A parte correspondente da subexpressão se torna o valor do atributo.
  6. O nome do atributo extraído substitui a parte correspondente no nome do log. Se os atributos já existirem no log, eles serão substituídos.

Esse processo é repetido para todas as regras na ordem em que são especificadas. Cada regra seguinte funciona no nome do log que é a saída da regra anterior.

"processors": [
  {
    "type": "log",
    "body": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

Critérios de inclusão e critérios de exclusão

Os processadores de log dão suporte aos critérios e opcionais include e exclude. Um processador de log é aplicado somente à telemetria que corresponde aos seus critérios include (se disponíveis) e não correspondem aos seus critérios exclude (se disponíveis).

Para configurar essa opção, em include ou exclude (ou ambos), especifique o matchType e o attributes. A configuração include ou exclude permite mais de uma condição especificada. Todas as condições especificadas devem ser avaliadas como true para resultar em uma correspondência.

  • Campo obrigatório:
    • matchType controla como os itens em attributes matrizes são interpretados. Os valores possíveis são regexp e strict. Correspondências de expressão regular são executadas com base no valor do atributo inteiro, portanto, se você quiser corresponder a um valor que contenha abc em qualquer lugar, use .*abc.*.
    • attributes especifica a lista de atributos a serem correspondentes. Todos esses atributos devem corresponder exatamente para resultar em uma correspondência.

Observação

Se ambos include e exclude forem especificados, as propriedades include serão verificadas antes da verificação das propriedades exclude.

Observação

Os processadores de log não dão suporte a spanNames.

Amostra de uso

"processors": [
  {
    "type": "log",
    "include": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute1",
          "value": "value1"
        }
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute2",
          "value": "value2"
        }
      ]
    },
    "body": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

Para obter mais informações, confira exemplos do processador de telemetria.

Filtro de métrica

Observação

Os filtros de métrica estão disponíveis a partir da versão 3.1.1.

Os filtros de métricas são usados para excluir algumas métricas a fim de ajudar a controlar o custo de ingestão.

Os filtros de métricas só dão suporte aos critérios exclude. As métricas que atendem aos critérios exclude não são exportadas.

Para configurar essa opção, em exclude, especifique o matchType ou mais metricNames.

  • Campo obrigatório:
    • matchType controla como os itens em metricNames correspondem. Os valores possíveis são regexp e strict. Correspondências de expressão regular são executadas com base no valor do atributo inteiro, portanto, se você quiser corresponder a um valor que contenha abc em qualquer lugar, use .*abc.*.
    • metricNames deve corresponder a pelo menos um dos itens.

Amostra de uso

O exemplo a seguir mostra como excluir métricas com nomes "metricA" e "metricB":

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "strict",
      "metricNames": [
        "metricA",
        "metricB"
      ]
    }
  }
]

O exemplo a seguir mostra como desativar todas as métricas, incluindo as métricas de desempenho padrão coletadas automaticamente, como CPU e memória.

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "regexp",
      "metricNames": [
        ".*"
      ]
    }
  }
]

Métricas padrão capturadas pelo agente Java

Nome da métrica Tipo de métrica Descrição Filtrável
Current Thread Count métricas personalizadas Consulte ThreadMXBean.getThreadCount(). sim
Loaded Class Count métricas personalizadas See ClassLoadingMXBean.getLoadedClassCount(). sim
GC Total Count métricas personalizadas Soma das contagens em todas as instâncias de GarbageCollectorMXBean (diferença desde o último relatório). Consulte GarbageCollectorMXBean.getCollectionCount(). sim
GC Total Time métricas personalizadas Soma do tempo em todas as instâncias de GarbageCollectorMXBean (diferença desde o último relatório). See GarbageCollectorMXBean.getCollectionTime(). sim
Heap Memory Used (MB) métricas personalizadas Consulte MemoryMXBean.getHeapMemoryUsage().getUsed(). sim
% Of Max Heap Memory Used métricas personalizadas java.lang:type=Memory / quantidade máxima de memória em bytes. Consulte MemoryUsage sim
\Processor(_Total)\% Processor Time métricas padrão Diferença nos contadores em escala de carga de CPU do sistema(Somente Usuário e Sistema) dividida pelo número de contagem de processadores lógicos em um determinado intervalo de tempo não
\Process(??APP_WIN32_PROC??)\% Processor Time métricas padrão Consulte OperatingSystemMXBean.getProcessCpuTime() (comparação desde o último relatório, normalizado por tempo e número de CPUs). não
\Process(??APP_WIN32_PROC??)\Private Bytes métricas padrão Soma de MemoryMXBean.getHeapMemoryUsage() e MemoryMXBean.getNonHeapMemoryUsage(). não
\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec métricas padrão /proc/[pid]/io Soma de bytes lidos e gravados pelo processo (comparação desde o último comunicado). Consulte proc(5). não
\Memory\Available Bytes métricas padrão See OperatingSystemMXBean.getFreePhysicalMemorySize(). não

Perguntas frequentes

Por que o processador de logs não processa arquivos de log usando TelemetryClient.trackTrace()?

TelemetryClient.trackTrace() faz parte da ponte do SDK Clássico do Application Insights e os processadores de log só funcionam com a nova instrumentação baseada em OpenTelemetry.