Exemplos de processadores de telemetria - Azure Monitor Application Insights for Java

Artigo
09/13/2024

Este artigo fornece exemplos de processadores de telemetria no Application Insights for Java, incluindo exemplos para incluir e excluir configurações. Ele também inclui amostras para processadores de atributos e processadores de extensão.

Incluir e excluir amostras de Span

Nesta seção, saiba como incluir e excluir vãos. Você também aprende a excluir várias extensões e aplicar o processamento seletivo.

Incluir vãos

Esta seção mostra como incluir extensões para um processador de atributos. O processador não processa extensões que não correspondam às propriedades.

Uma correspondência requer que o nome da extensão seja igual a spanA ou spanB.

Essas extensões correspondem às include propriedades e as ações do processador são aplicadas:

Span1 Nome: 'spanA' Atributos: {env: dev, test_request: 123, credit_card: 1234}
Span2 Nome: 'spanB' Atributos: {env: dev, test_request: false}
Span3 Nome: 'spanA' Atributos: {env: 1, test_request: dev, credit_card: 1234}

Essa extensão não corresponde às include propriedades e as ações do processador não são aplicadas:

Span4 Nome: 'spanC' Atributos: {env: dev, test_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Excluir extensões

Esta seção demonstra como excluir extensões para um processador de atributo. Este processador não processa extensões que correspondam às propriedades.

Uma correspondência requer que o nome da extensão seja igual a spanA ou spanB.

As extensões a seguir correspondem às exclude propriedades e as ações do processador não são aplicadas:

Span1 Nome: 'spanA' Atributos: {env: dev, test_request: 123, credit_card: 1234}
Span2 Nome: 'spanB' Atributos: {env: dev, test_request: false}
Span3 Nome: 'spanA' Atributos: {env: 1, test_request: dev, credit_card: 1234}

Essa extensão não corresponde às exclude propriedades e as ações do processador são aplicadas:

Span4 Nome: 'spanC' Atributos: {env: dev, test_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Excluir extensões usando vários critérios

Esta seção demonstra como excluir extensões para um processador de atributo. Este processador não processa extensões que correspondam às propriedades.

Uma correspondência requer o cumprimento das seguintes condições:

Um atributo (por exemplo, env com valor dev) deve existir na extensão.
A extensão deve ter um atributo que tenha a chave test_request.

As extensões a seguir correspondem às exclude propriedades e as ações do processador não são aplicadas.

Span1 Nome: 'spanB' Atributos: {env: dev, test_request: 123, credit_card: 1234}
Span2 Nome: 'spanA' Atributos: {env: dev, test_request: false}

A extensão a seguir não corresponde às exclude propriedades e as ações do processador são aplicadas:

Span3 Nome: 'spanB' Atributos: {env: 1, test_request: dev, credit_card: 1234}
Span4 Nome: 'spanC' Atributos: {env: dev, dev_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ],
          "attributes": [
            {
              "key": "env",
              "value": "dev"
            },
            {
              "key": "test_request"
            }
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Processamento seletivo

Esta seção mostra como especificar o conjunto de propriedades de span que indicam a quais extensões esse processador deve ser aplicado. As include propriedades indicam quais vãos devem ser processados. As exclude propriedades filtram extensões que não devem ser processadas.

Na configuração a seguir, essas extensões correspondem às propriedades e as ações do processador são aplicadas:

Span1 Nome: 'spanB' Atributos: {env: production, test_request: 123, credit_card: 1234, redact_trace: "false"}
Span2 Nome: 'spanA' Atributos: {env: preparo, test_request: false, redact_trace: true}

Essas extensões não correspondem às propriedades e as include ações do processador não são aplicadas:

Span3 Nome: 'spanB' Atributos: {env: production, test_request: true, credit_card: 1234, redact_trace: false}
Span4 Nome: 'spanC' Atributos: {env: dev, test_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "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"
          }
        ]
      }
    ]
  }
}

Exemplos de processador de atributos

Inserir

O exemplo a seguir insere o novo atributo {"attribute1": "attributeValue1"} em extensões e logs onde a chave attribute1 não existe.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "attribute1",
            "value": "attributeValue1",
            "action": "insert"
          }
        ]
      }
    ]
  }
}

Inserir a partir de outra chave

O exemplo a seguir usa o valor do atributo anotherkey para inserir o novo atributo {"newKey": "<value from attribute anotherkey>"} em extensões e logs onde a chave newKey não existe. Se o atributo anotherkey não existir, nenhum novo atributo será inserido em extensões e logs.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "newKey",
            "fromAttribute": "anotherKey",
            "action": "insert"
          }
        ]
      }
    ]
  }
}

Atualizar

O exemplo a seguir atualiza o atributo para {"db.secret": "redacted"}. Ele atualiza o atributo boo usando o valor do atributo foo. Espadas e logs que não têm o atributo boo não são alterados.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "db.secret",
            "value": "redacted",
            "action": "update"
          },
          {
            "key": "boo",
            "fromAttribute": "foo",
            "action": "update" 
          }
        ]
      }
    ]
  }
}

Delete

O exemplo a seguir mostra como excluir um atributo que tem a chave credit_card.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Hash

O exemplo a seguir mostra como hash valores de atributos existentes.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "user.email",
            "action": "hash"
          }
        ]
      }
    ]
  }
}

Extrair

O exemplo a seguir mostra como usar uma expressão regular (regex) para criar novos atributos com base no valor de outro atributo. Por exemplo, dado url.path = /path?queryParam1=value1,queryParam2=value2, os seguintes atributos são inseridos:

Protocolo http: http
Domínio http: example.com
httpCaminho: path
httpQueryParams: queryParam1=value1,queryParam2=value2
url.path: sem alteração

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "^(?<httpProtocol>.*):\\/\\/(?<httpDomain>.*)\\/(?<httpPath>.*)(\\?|\\&)(?<httpQueryParams>.*)",
            "action": "extract"
          }
        ]
      }
    ]
  }
}

Máscara

Por exemplo, dado url.path = https://example.com/user/12345622 é atualizado para url.path = https://example.com/user/**** usar qualquer uma das configurações abaixo.

Primeiro exemplo de configuração:

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "user\\/\\d+",
            "replace": "user\\/****",
            "action": "mask"
          }
        ]
      }
    ]
  }
}

Segundo exemplo de configuração com nome de grupo de expressões regulares:

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "^(?<userGroupName>[a-zA-Z.:\/]+)\d+",
            "replace": "${userGroupName}**",
            "action": "mask"
          }
        ]
      }
    ]
  }
}

Exemplos de atributos digitados sem cadeia de caracteres

A partir da versão 3.4.19 GA, os processadores de telemetria suportam atributos não tipados por cadeia de caracteres: boolean, , , boolean-arraylong, double-array, long-array, e string-arraydouble.

Quando attributes.type não é fornecido no json, o padrão é .string

O exemplo a seguir insere o novo atributo {"newAttributeKeyStrict": "newAttributeValueStrict"} em extensões e logs onde os atributos correspondem aos seguintes exemplos: {"longAttributeKey": 1234}{"booleanAttributeKey": true}{"doubleArrayAttributeKey": [1.0, 2.0, 3.0, 4.0]}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            {
              "key": "longAttributeKey",
              "value": 1234,
              "type": "long"
            },
            {
              "key": "booleanAttributeKey",
              "value": true,
              "type": "boolean"
            },
            {
              "key": "doubleArrayAttributeKey",
              "value": [1.0, 2.0, 3.0, 4.0],
              "type": "double-array"
            }
          ]
        },
        "actions": [
          {
            "key": "newAttributeKeyStrict",
            "value": "newAttributeValueStrict",
            "action": "insert"
          }
        ],
        "id": "attributes/insertNewAttributeKeyStrict"
      }
    ]
  }
}

Além disso, atributos não tipados de cadeia de caracteres suportam regexp.

O exemplo a seguir insere o novo atributo {"newAttributeKeyRegexp": "newAttributeValueRegexp"} em extensões e logs onde o atributo longRegexpAttributeKey corresponde ao valor de 400 para 499.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "regexp",
          "attributes": [
            {
              "key": "longRegexpAttributeKey",
              "value": "4[0-9][0-9]",
              "type": "long"
            }
          ]
        },
        "actions": [
          {
            "key": "newAttributeKeyRegexp",
            "value": "newAttributeValueRegexp",
            "action": "insert"
          }
        ],
        "id": "attributes/insertNewAttributeKeyRegexp"
      }
    ]
  }
}

Amostras do processador Span

Nomeie uma extensão

O exemplo a seguir especifica os valores dos atributos db.svc, operatione id. Ele forma o novo nome da extensão usando esses atributos, nessa ordem, separados pelo valor ::.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "name": {
          "fromAttributes": [
            "db.svc",
            "operation",
            "id"
          ],
          "separator": "::"
        }
      }
    ]
  }
}

Extrair atributos de um nome de extensão

Vamos supor que o nome da extensão de entrada seja /api/v1/document/12345678/update. O exemplo a seguir resulta no nome /api/v1/document/{documentId}/updateda extensão de saída . Ele adiciona o novo atributo documentId=12345678 à extensão.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "name": {
          "toAttributes": {
            "rules": [
              "^/api/v1/document/(?<documentId>.*)/update$"
            ]
          }
        }
      }
    ]
  }
}

Extrair atributos de um nome de extensão usando incluir e excluir

O exemplo a seguir mostra como alterar o nome da extensão para {operation_website}. Ele adiciona um atributo com chave operation_website e valor {oldSpanName} quando a extensão tem as seguintes propriedades:

O nome da extensão contém / qualquer lugar na cadeia de caracteres.
O nome da extensão não donot/changeé .

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "include": {
          "matchType": "regexp",
          "spanNames": [
            "^(.*?)/(.*?)$"
          ]
        },
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "donot/change"
          ]
        },
        "name": {
          "toAttributes": {
            "rules": [
              "(?<operation_website>.*?)$"
            ]
          }
        }
      }
    ]
  }
}

Amostras do processador de log

Extrair atributos de um corpo de mensagem de log

Vamos supor que o corpo da mensagem do log de entrada seja Starting PetClinicApplication on WorkLaptop with PID 27984 (C:\randompath\target\classes started by userx in C:\randompath). O exemplo a seguir resulta no corpo Starting PetClinicApplication on WorkLaptop with PID {PIDVALUE} (C:\randompath\target\classes started by userx in C:\randompath)da mensagem de saída. Ele adiciona o novo atributo PIDVALUE=27984 ao log.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "log",
        "body": {
          "toAttributes": {
            "rules": [
              "^Starting PetClinicApplication on WorkLaptop with PID (?<PIDVALUE>\\d+) .*"
            ]
          }
        }
      }
    ]
  }
}

Mascarar dados confidenciais na mensagem de log

O exemplo a seguir mostra como mascarar dados confidenciais em um corpo de mensagem de log usando o processador de log e o processador de atributos. Vamos supor que o corpo da mensagem do log de entrada seja User account with userId 123456xx failed to login. O processador de log atualiza o corpo da mensagem de saída e User account with userId {redactedUserId} failed to login o processador de atributos exclui o novo atributo redactedUserId, que foi adicionado na etapa anterior.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "log",
        "body": {
          "toAttributes": {
            "rules": [
              "userId (?<redactedUserId>[0-9a-zA-Z]+)"
            ]
          }
        }
      },
      {
        "type": "attribute",
        "actions": [
          {
            "key": "redactedUserId",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

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.

Partilhar via