Compartilhar via

Exemplos de processador de telemetria – Application Insights do Azure Monitor para Java

  • Artigo

Este artigo fornece exemplos de processadores de telemetria no Application Insights para Java, incluindo exemplos de configurações de inclusão e exclusão. Ele também inclui exemplos para processadores de atributo e processadores de intervalo.

Incluir e excluir exemplos de intervalo

Nesta seção, descubra como incluir e excluir intervalos. Você também aprenderá como excluir vários intervalos e aplicar o processamento seletivo.

Incluir intervalos

Esta seção mostra como incluir intervalos para um processador de atributo. O processador não processa intervalos que não correspondem às propriedades.

Uma correspondência requer que o nome de do intervalo seja igual a spanA ou spanB.

Estes intervalos correspondem às propriedades include, e as ações do processador são aplicadas:

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

Esse intervalo não corresponde às propriedades include, e as ações do processador não são aplicadas:

  • Span4 Name: 'spanC' Attributes: {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 intervalos

Esta seção demonstra como excluir intervalos para um processador de atributo. Esse processador não processa intervalos que correspondam às propriedades.

Uma correspondência requer que o nome de do intervalo seja igual a spanA ou spanB.

Os seguintes intervalos correspondem às propriedades exclude, e as ações do processador não são aplicadas:

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

Este intervalo não corresponde às propriedades exclude, e as ações do processador são aplicadas:

  • Span4 Name: 'spanC' Attributes: {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 intervalos usando vários critérios

Esta seção demonstra como excluir intervalos para um processador de atributo. Esse processador não processa intervalos que correspondam às propriedades.

Uma correspondência requer que as seguintes condições sejam atendidas:

  • Um atributo (por exemplo, env com valor dev) precisa existir no intervalo.
  • O intervalo deve ter um atributo que tenha a chave test_request.

Os intervalos a seguir correspondem às propriedades exclude, e as ações do processador não são aplicadas.

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

O seguinte intervalo não corresponde às propriedades exclude, e as ações do processador são aplicadas:

  • Nome de Span3: 'spanB' Atributos: {env: 1, test_request: dev, credit_card: 1234}
  • Span4 Name: 'spanC' Attributes: {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 intervalo que indicam a quais intervalos esse processador deve ser aplicado. As propriedades include indicam quais intervalos devem ser processados. As propriedades exclude filtram intervalos que não devem ser processados.

Na seguinte configuração, esses intervalos correspondem às propriedades, e as ações do processador são aplicadas:

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

Estes intervalos não correspondem às propriedades include, e as ações do processador não são aplicadas:

  • Nome de Span3: 'spanB' Atributos: {env: production, test_request: true, credit_card: 1234, redact_trace: false}
  • Span4 Name: 'spanC' Attributes: {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 intervalos e registra 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"
          }
        ]
      }
    ]
  }
}

Fazer inserção de outra chave

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

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

Atualização

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

{
  "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" 
          }
        ]
      }
    ]
  }
}

Excluir

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 realizar hash de valores de atributo existentes.

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

Extract

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

  • httpProtocol: http
  • httpDomain: example.com
  • httpPath: path
  • httpQueryParams: queryParam1=value1,queryParam2=value2
  • url.path: nenhuma 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 que url.path = https://example.com/user/12345622 é atualizado para url.path = https://example.com/user/**** usando 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 o nome do 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"
          }
        ]
      }
    ]
  }
}

Amostras de atributos com tipo que não são cadeias de caracteres

A partir da versão 3.4.19 GA, os processadores de telemetria dão suporte a atributos com tipo que não são cadeias de caracteres: boolean, double, long, boolean-array, double-array, long-array e string-array.

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

O exemplo a seguir insere o novo atributo {"newAttributeKeyStrict": "newAttributeValueStrict"} em períodos e registros em que 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, os atributos com tipo que não são cadeias de caracteres dão suporte para regexp.

O exemplo a seguir insere o novo atributo {"newAttributeKeyRegexp": "newAttributeValueRegexp"} em períodos e registros em que o atributo longRegexpAttributeKey corresponde ao valor de 400 a 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"
      }
    ]
  }
}

Exemplos de processador de intervalo

Dar nome a um intervalo

O exemplo a seguir especifica os valores dos atributos db.svc, operation e id. Ele forma o novo nome do intervalo 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 do nome de um intervalo

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

{
  "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 intervalo usando incluir e excluir

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

  • O nome do intervalo contém / em qualquer lugar na cadeia de caracteres.
  • O nome do intervalo 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>.*?)$"
            ]
          }
        }
      }
    ]
  }
}

Exemplos de processador de log

Extrair atributos do corpo de uma 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 da mensagem de saída Starting PetClinicApplication on WorkLaptop with PID {PIDVALUE} (C:\randompath\target\classes started by userx in C:\randompath). 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+) .*"
            ]
          }
        }
      }
    ]
  }
}

Como mascarar dados confidenciais na mensagem do log

O exemplo a seguir mostra como mascarar dados confidenciais em um corpo de mensagem do log usando o processador de log e o processador de atributo. 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 para User account with userId {redactedUserId} failed to login e o processador de atributo exclui o novo atributo redactedUserId que estava adicionando 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 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.