Processadores de telemetria (pré-visualização) - Azure Monitor Application Insights para Java

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 do intervalo, que é usado para agregar telemetria semelhante no portal do Azure.
• Remova atributos específicos de span para controlar os custos de ingestão.
• Filtre algumas métricas para controlar os custos de ingestão.

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 do intervalo é 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 fazer hash de atributos 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 registos pode atualizar o nome da telemetria dos registos. 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.

Primeiros Passos

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

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 comporta-se como a configuração do processador spantoAttributes, 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

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 corresponder. Todos esses atributos devem corresponder exatamente para resultar em uma correspondência.

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. Permite incluir ou excluir intervalos.

Nomeie uma extensão

A name seção requer a configuração fromAttributes. 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.

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

Extrair atributos do nome do span

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. Esta configuração lista as regras usadas para extrair valores de atributos do nome do span.

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 da expressão regular (regex) são extraídas como atributos se corresponder ao regex.
3. Os atributos extraídos são adicionados ao trecho.
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 span, serão substituídos.

Esse processo é repetido para todas as regras na ordem em que são especificadas. Cada regra subsequente aplica-se ao nome do intervalo que é o resultado da regra anterior.

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

Atributos comuns de span

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

Intervalos HTTP

A conectividade de banco de dados Java abrange

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

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 esta opção, em include ou exclude (ou ambos), especifique pelo menos um matchType e um spanNames ou um intervalo 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 corresponder. Todos esses atributos devem corresponder exatamente para resultar em uma correspondência.

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

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. Pode suportar a inclusão ou exclusão de registos.

Corpo da mensagem Atualizar Log

A body seção requer a configuração fromAttributes. 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.

"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 da expressão regular (regex) são extraídas como atributos se corresponder ao regex.
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 aplica-se ao 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 opcionais, assim como include e exclude. 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 corresponder. Todos esses atributos devem corresponder exatamente para resultar em uma correspondência.

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

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 apenas suportam critérios exclude. 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 em metricNames são 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

Próximos passos

• Para rever as perguntas frequentes (FAQ), consulte Perguntas frequentes sobre processadores de telemetria