Ejemplos de procesadores de telemetría: Azure Monitor Application Insights para Java

Artículo
04/24/2024

En este artículo se proporcionan ejemplos de procesadores de telemetría en Application Insights para Java, e incluye ejemplos para incluir y excluir configuraciones. También incluye ejemplos de procesadores de atributos y procesadores de intervalos.

Ejemplos de inclusión y exclusión de intervalos

En esta sección aprenderá a incluir y excluir intervalos. También aprenderá a excluir varios intervalos y a aplicar un procesamiento selectivo.

Inclusión de intervalos

En esta sección se muestra cómo incluir intervalos para un procesador de atributos. El procesador no procesa los intervalos que no coinciden con las propiedades.

Una coincidencia requiere que el nombre del intervalo sea igual a spanA o spanB.

Los siguientes intervalos coinciden con las propiedades include, por lo que se aplican las acciones del procesador:

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

Este intervalo no coincide con las propiedades include, de modo que las acciones del procesador no se aplican:

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

Exclusión de intervalos

En esta sección se muestra cómo excluir intervalos para un procesador de atributos. Este procesador no procesa los intervalos que coinciden con las propiedades.

Una coincidencia requiere que el nombre del intervalo sea igual a spanA o spanB.

Los siguientes intervalos coinciden con las propiedades exclude, por lo que no se aplican las acciones del procesador:

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

Este intervalo no coincide con las propiedades exclude y se aplican las acciones del procesador:

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

Exclusión de intervalos mediante varios criterios

En esta sección se muestra cómo excluir intervalos para un procesador de atributos. Este procesador no procesa los intervalos que coinciden con las propiedades.

Una coincidencia requiere que se cumplan las siguientes condiciones:

Debe haber un atributo (por ejemplo, env con el valor dev) en el intervalo.
El intervalo debe tener un atributo con la clave test_request.

Los siguientes intervalos coinciden con las propiedades exclude, por lo que no se aplican las acciones del procesador.

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

El siguiente intervalo no coincide con las propiedades exclude, de modo que se aplican las acciones del procesador:

Span3 Nombre: '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"
          }
        ]
      }
    ]
  }
}

Procesamiento selectivo

En esta sección se muestra cómo especificar el conjunto de propiedades de los intervalos que indican a qué intervalos se debe aplicar este procesador. Las propiedades include indican qué intervalos se deben procesar. Las propiedades exclude filtran los intervalos que no se deben procesar.

Con la siguiente configuración, estos intervalos coinciden con las propiedades y se aplican las acciones del procesador:

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

Estos intervalos no coinciden con las propiedades include, de modo que las acciones del procesador no se aplican:

Span3 Nombre: '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"
          }
        ]
      }
    ]
  }
}

Ejemplos de procesador de atributos

Insertar

En el ejemplo siguiente se inserta el nuevo atributo {"attribute1": "attributeValue1"} en intervalos y registros en los que la clave attribute1 no existe.

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

Inserción desde otra clave

En el ejemplo siguiente se usa el valor del atributo anotherkey para insertar el nuevo atributo {"newKey": "<value from attribute anotherkey>"} en intervalos y registros en los que la clave newKey no existe. Si el atributo anotherkey no existe, no se inserta ningún atributo nuevo en los intervalos y registros.

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

Actualizar

En el ejemplo siguiente se actualiza el atributo a {"db.secret": "redacted"}. El atributo boo se actualiza con el valor del atributo foo. Los intervalos y registros que no tienen el atributo boo no cambian.

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

Eliminar

En el ejemplo siguiente se muestra cómo eliminar un atributo que tiene la clave credit_card.

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

Hash

En el ejemplo siguiente se muestra cómo aplicar un algoritmo hash a los valores de atributo existentes.

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

Extract

En el ejemplo siguiente se muestra cómo usar una expresión regular (regex) para crear nuevos atributos basados en el valor de otro atributo. Por ejemplo, si tenemos url.path = /path?queryParam1=value1,queryParam2=value2, se insertarán los siguientes atributos:

httpProtocol: http
httpDomain: example.com
httpPath: path
httpQueryParams: queryParam1=value1,queryParam2=value2
url.path: ningún cambio

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

Mask

Por ejemplo, url.path = https://example.com/user/12345622 se actualiza a url.path = https://example.com/user/**** utilizando cualquiera de las siguientes configuraciones.

Primer ejemplo de configuración:

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

Segundo ejemplo de configuración con el nombre del grupo de expresiones 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"
          }
        ]
      }
    ]
  }
}

Ejemplos de atributos con tipo que no son cadenas

A partir de la versión 3.4.19 de disponibilidad general, los procesadores de telemetría admiten atributos con tipo que no son cadenas: boolean, double, long, boolean-array, double-array, long-array y string-array.

Cuando no se proporciona attributes.type en el JSON, el valor predeterminado es string.

En el ejemplo siguiente se inserta el nuevo atributo {"newAttributeKeyStrict": "newAttributeValueStrict"} en intervalos y registros en los que los atributos coinciden con los siguientes ejemplos: {"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"
      }
    ]
  }
}

Además, los atributos con tipo que no son cadenas admiten regexp.

En el ejemplo siguiente se inserta el nuevo atributo {"newAttributeKeyRegexp": "newAttributeValueRegexp"} en intervalos y registros donde el atributo longRegexpAttributeKey coincide con el 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"
      }
    ]
  }
}

Ejemplos de procesador de intervalos

Asignación de un nombre para un intervalo

En el ejemplo siguiente se especifican los valores de los atributos db.svc, operation y id. Forma el nuevo nombre del intervalo mediante esos atributos, en ese orden, separados por el valor ::.

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

Extracción de atributos del nombre de un intervalo

Supongamos que el nombre del intervalo de entrada es /api/v1/document/12345678/update. En el ejemplo siguiente se obtiene el nombre del intervalo de salida /api/v1/document/{documentId}/update. Agrega el nuevo atributo documentId=12345678 al intervalo.

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

Extracción de atributos del nombre de un intervalo con inclusión y exclusión

En el ejemplo siguiente se muestra cómo cambiar el nombre del intervalo a {operation_website}. Agrega un atributo con la clave operation_website y el valor {oldSpanName} cuando el intervalo tiene las siguientes propiedades:

El nombre del intervalo contiene / en cualquier parte de la cadena.
El nombre del intervalo no es 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>.*?)$"
            ]
          }
        }
      }
    ]
  }
}

Ejemplos de procesador de registros

Extracción de atributos del cuerpo del mensaje de un registro

Supongamos que el cuerpo del mensaje del registro de entrada es Starting PetClinicApplication on WorkLaptop with PID 27984 (C:\randompath\target\classes started by userx in C:\randompath). En el ejemplo siguiente se obtiene el cuerpo del mensaje de salida Starting PetClinicApplication on WorkLaptop with PID {PIDVALUE} (C:\randompath\target\classes started by userx in C:\randompath). Agrega el nuevo atributo PIDVALUE=27984 al registro.

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

Enmascaramiento de datos confidenciales en el mensaje de registro

En el ejemplo siguiente se muestra cómo enmascarar datos confidenciales en el cuerpo del mensaje de un registro mediante el procesador de registros y el procesador de atributos. Supongamos que el cuerpo del mensaje del registro de entrada es User account with userId 123456xx failed to login. El procesador de registros actualiza el cuerpo del mensaje de salida a User account with userId {redactedUserId} failed to login, y el procesador de atributos elimina el nuevo atributo redactedUserId que se agregaba en el paso 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"
          }
        ]
      }
    ]
  }
}

Preguntas más frecuentes

¿Por qué el procesador de registros no procesa los archivos de registro mediante TelemetryClient.trackTrace()?

TelemetryClient.trackTrace() forma parte del puente del SDK clásico de Application Insights y los procesadores de registro solo funcionan con la nueva instrumentación basada en OpenTelemetry.

Share via