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

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.

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.

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

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 span toAttributes, 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

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.

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.

"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

Spans do Java Database Connectivity

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

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.

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

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.

"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.

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

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

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.