Partilhar via

Processadores de telemetria (visualização) - Azure Monitor Application Insights for Java

  • Artigo

Nota

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

O Application Insights Java 3.x pode processar dados de telemetria antes que os dados sejam exportados.

Alguns casos de uso:

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

Nota

Se você estiver procurando eliminar extensões específicas (inteiras) para controlar o custo de ingestão, consulte substituições de amostragem.

Terminologia

Antes de aprender sobre 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, estes componentes de extensão/log são importantes:

  • Nome
  • Corpo
  • Atributos

O nome da extensão é a exibição principal para solicitações e dependências no portal do Azure. Os atributos Span representam propriedades padrão e personalizadas de uma determinada solicitação ou dependência.

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

Tipos de processadores de telemetria

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

  • Processadores de atributos
  • Processadores Span
  • Processadores de log
  • Filtros métricos

Um processador de atributos pode inserir, atualizar, eliminar ou criar hashes de atributos a partir de um item de telemetria (span ou log). Ele também pode usar uma expressão regular para extrair um ou mais novos atributos de um atributo existente.

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

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

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

Nota

Atualmente, os processadores de telemetria processam apenas atributos do tipo string. Eles não processam atributos do tipo booleano ou número.

Introdução

Para começar, crie um arquivo de configuração chamado applicationinsights.json. Salve-o no mesmo diretório que applicationinsights-agent-*.jar. Utilize o modelo seguinte.

{
  "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 modifica atributos de um span ou um logarquivo . Pode apoiar a capacidade de span incluir ou excluir ou log. Ele usa uma lista de ações que são executadas na ordem especificada pelo arquivo de configuração. O processador suporta estas ações:

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

insert

A insert ação insere um novo atributo no item de telemetria onde o key ainda não existe.

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

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

  • key
  • Tanto value como fromAttribute
  • action: insert

update

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

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

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

  • key
  • Tanto value como fromAttribute
  • action: update

delete

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

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

A delete ação 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 hash ação requer as seguintes configurações:

  • key
  • action: hash

extract

Nota

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

A extract ação extrai valores usando uma regra de expressão regular da chave de entrada para as chaves de destino especificadas pela regra. Se já existir uma chave de destino, a extract ação substitui a chave de destino. Essa ação se comporta como a configuração do processador toAttributes span, onde o atributo existente é a origem.

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

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

  • key
  • pattern
  • action: extract

mask

Nota

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

A mask ação 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 mask ação 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 então conter o mesmo grupo nomeado colocado entre ${ e } seguido pela máscara. Exemplo em que a máscara é **: ${userGroupName}**.

Consulte Exemplos de processadores de telemetria para obter exemplos de mascaramento.

Incluir critérios e excluir critérios

Os processadores de atributos suportam opcionais include e exclude critérios. Um processador de atributos é aplicado apenas à telemetria que corresponde aos seus include critérios (se estiver disponível) e não corresponde aos seus exclude critérios (se estiver disponível).

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

  • Campos obrigatórios:

    • matchType Controla como os itens em spanNames matrizes e attributes matrizes são interpretados. Os valores possíveis são regexp e strict. As correspondências de expressão regular são realizadas em relação ao valor do atributo inteiro, portanto, se você quiser corresponder a um valor que contenha abc qualquer lugar nele, precisará usar .*abc.*o .

  • Campos opcionais:

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

Nota

Se ambos include forem exclude especificados, as propriedades serão verificadas include antes de serem exclude verificadas.

Nota

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

Uso da amostra

"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, consulte Exemplos de processadores de telemetria.

Processador Span

O processador span modifica o nome da extensão ou os atributos de uma extensão com base no nome da extensão. Ele pode suportar a capacidade de incluir ou excluir vãos.

Nomeie uma extensão

A name seção requer a fromAttributes configuração. Os valores desses atributos são usados para criar um novo nome, concatenado na ordem especificada pela configuração. O processador altera o nome da extensão somente se todos esses atributos estiverem presentes na extensão.

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

Nota

Se a renomeação depender do processador de atributos para modificar atributos, certifique-se de que o processador span seja especificado após o processador de atributos na especificação do pipeline.

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

Extrair atributos do nome da extensão

A toAttributes seção lista as expressões regulares para corresponder ao nome da extensão. Ele extrai atributos com base em subexpressões.

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

Os nomes de atributos extraídos substituem os valores no nome da extensão. 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 os valores:

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

Esse processo é repetido para todas as regras na ordem em que são especificadas. Cada regra subsequente funciona no nome da extensão 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.

Extensões HTTP

Atributo Tipo Description
http.request.method (costumava ser http.method) string Método de solicitação HTTP.
url.full (client span) ou url.path (server span) (costumava ser http.url) string URL de solicitação HTTP completa no formato scheme://host[:port]/path?query[#fragment]. O fragmento normalmente não é transmitido por HTTP. Mas se o fragmento for conhecido, deve ser incluído.
http.response.status_code (costumava ser http.status_code) Número Código de status da 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 HTTP User-Agent enviado pelo cliente.

Abrange a conectividade do banco de dados Java

A tabela a seguir descreve os atributos que você pode usar em extensões JDBC (Java Database Connectivity):

Atributo Tipo Description
db.system string Identificador do produto DBMS (sistema de gerenciamento de banco de dados) que está sendo usado. Consulte Convenções semânticas para operações de banco de dados.
db.connection_string string Cadeia de conexão usada para se conectar ao banco de dados. Recomendamos que remova as credenciais incorporadas.
db.user string Nome de utilizador para aceder à base de dados.
db.name string String usada para relatar o nome do banco de dados que está sendo acessado. Para comandos que alternam o banco de dados, essa cadeia de caracteres deve ser definida como o banco de dados de destino, mesmo que o comando falhe.
db.statement string Instrução de banco de dados que está sendo executada.

Incluir critérios e excluir critérios

Os processadores Span suportam opcionais include e exclude critérios. Um processador span é aplicado apenas à telemetria que corresponde aos seus include critérios (se estiver disponível) e não corresponde aos seus exclude critérios (se estiver disponível).

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

  • Campos obrigatórios:

    • matchType Controla como os itens em spanNames matrizes e attributes matrizes são interpretados. Os valores possíveis são regexp e strict. As correspondências de expressão regular são realizadas em relação ao valor do atributo inteiro, portanto, se você quiser corresponder a um valor que contenha abc qualquer lugar nele, precisará usar .*abc.*o .

  • Campos opcionais:

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

Nota

Se ambos include forem exclude especificados, as propriedades serão verificadas include antes de serem exclude verificadas.

Uso da amostra

"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, consulte Exemplos de processadores de telemetria.

Processador de log

Nota

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 de log ou os atributos de um log com base no corpo da mensagem de log. Ele pode suportar a capacidade de incluir ou excluir logs.

Corpo da mensagem Atualizar Log

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

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

Nota

Se a renomeação depender do processador de atributos para modificar atributos, certifique-se de que o processador de log seja especificado após o processador de atributos na especificação de pipeline.

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

Extrair atributos do corpo da mensagem de log

A toAttributes seção lista as expressões regulares para corresponder ao corpo da mensagem de log. Ele extrai atributos com base em subexpressões.

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

Os nomes de atributos extraídos substituem os valores no corpo da mensagem de 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 os valores:

  1. O corpo da mensagem de log é verificado em relação ao regex.
  2. Todas as subexpressões nomeadas do regex são extraídas como atributos se o regex corresponder.
  3. Os atributos extraídos são adicionados ao log.
  4. Cada nome de subexpressão torna-se um nome de atributo.
  5. A parte correspondente da subexpressão torna-se 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 subsequente funciona no nome do log que é a saída da regra anterior.

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

Incluir critérios e excluir critérios

Os processadores de log suportam critérios e exclude opcionaisinclude. Um processador de log é aplicado apenas à telemetria que corresponde aos seus include critérios (se estiver disponível) e não corresponde aos seus exclude critérios (se estiver disponível).

Para configurar essa opção, em include ou exclude (ou ambos), especifique o matchType e attributes. A include configuração ou exclude permite mais de uma condição especificada. Todas as condições especificadas devem ser avaliadas como verdadeiras 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. As correspondências de expressão regular são realizadas em relação ao valor do atributo inteiro, portanto, se você quiser corresponder a um valor que contenha abc qualquer lugar nele, precisará usar .*abc.*o .
    • attributes Especifica a lista de atributos a serem correspondidos. Todos esses atributos devem corresponder exatamente para resultar em uma correspondência.

Nota

Se ambos include forem exclude especificados, as propriedades serão verificadas include antes de serem exclude verificadas.

Nota

Os processadores de log não suportam spanNames.

Uso da amostra

"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, consulte Exemplos de processadores de telemetria.

Filtro métrico

Nota

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

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

Os filtros métricos suportam exclude apenas critérios. As métricas que correspondem aos seus exclude critérios não são exportadas.

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

  • Campo obrigatório:
    • matchType Controla como os itens são metricNames correspondidos. Os valores possíveis são regexp e strict. As correspondências de expressão regular são realizadas em relação ao valor do atributo inteiro, portanto, se você quiser corresponder a um valor que contenha abc qualquer lugar nele, precisará usar .*abc.*o .
    • metricNames deve corresponder a pelo menos um dos itens.

Uso da amostra

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 Description Filtrável
Current Thread Count métricas personalizadas Consulte ThreadMXBean.getThreadCount(). sim
Loaded Class Count métricas personalizadas Consulte ClassLoadingMXBean.getLoadedClassCount(). sim
GC Total Count métricas personalizadas Soma das contagens em todas as instâncias GarbageCollectorMXBean (diff desde o último relatado). Consulte GarbageCollectorMXBean.getCollectionCount(). sim
GC Total Time métricas personalizadas Soma de tempo em todas as instâncias GarbageCollectorMXBean (diff desde o último relatado). Consulte 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=Memória / quantidade máxima de memória em bytes. Consulte MemoryUsage sim
\Processor(_Total)\% Processor Time Métricas padrão Diferença nos contadores de ticks de carga da CPU em todo o sistema (Somente Usuário e Sistema) dividida pelo número de processadores lógicos contados em um determinado intervalo de tempo não
\Process(??APP_WIN32_PROC??)\% Processor Time Métricas padrão Consulte OperatingSystemMXBean.getProcessCpuTime() (diff desde o último relatado, 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 (diff desde o último relatado). Ver proc(5). não
\Memory\Available Bytes Métricas padrão Consulte OperatingSystemMXBean.getFreePhysicalMemorySize(). não

Perguntas mais frequentes

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

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