Procesadores de telemetría (versión preliminar): Azure Monitor Application Insights para Java

Artículo
04/25/2024

Nota

La característica de procesadores de telemetría se designa como versión preliminar porque no se puede garantizar la compatibilidad con versiones anteriores entre versiones debido al estado experimental de las convenciones semánticas de los atributos. Sin embargo, se ha probado la característica y se admite en producción.

Application Insights Java 3.x puede procesar los datos de telemetría antes de que estos se exporten.

Algunos casos de uso:

Máscara de datos confidenciales.
Adición de dimensiones personalizadas condicionalmente
Actualizar el nombre del intervalo, que se usa para agregar telemetría similar en Azure Portal
Anulación de atributos de intervalo específicos para controlar los costos de ingesta.
Filtre algunas métricas para controlar los costos de ingesta.

Nota

Si quiere anular intervalos específicos (completos) para controlar el costo de la ingesta, consulte las invalidaciones de muestreo.

Terminología

Antes de obtener información sobre los procesadores de telemetría, debe comprender los términos intervalo y registro.

Un intervalo es un tipo de telemetría que representa una de las siguientes opciones:

Un solicitud entrante
Una dependencia saliente (por ejemplo, una llamada remota a otro servicio)
Una dependencia en proceso (por ejemplo, trabajo realizado por los subcomponentes del servicio)

Un registro es un tipo de telemetría que representa:

Datos de registro capturados de Log4j, Logback y java.util.logging

En el caso de los procesadores de telemetría, estos componentes de intervalo o registro son importantes:

Nombre
Cuerpo
Atributos

El nombre del intervalo es el elemento mostrado principal para solicitudes y dependencias en Azure Portal. Los atributos de intervalo representan tanto propiedades estándar como personalizadas de una determinada solicitud o dependencia.

El mensaje o cuerpo de seguimiento es la presentación principal de los registros de Azure Portal. Los atributos de registro representan tanto propiedades estándar como personalizadas de un determinado registro.

Tipos de procesadores de telemetría

Actualmente, los cuatro tipos de procesadores de telemetría son:

Procesadores de atributos
Procesadores de intervalos
Procesadores de registro
Filtros de métricas

Un procesador de atributos puede insertar, actualizar, eliminar o aplicar algoritmos hash a atributos de un elemento de telemetría (span o log). También puede usar una expresión regular para extraer uno o más atributos nuevos de un atributo existente.

Un procesador de intervalos puede actualizar el nombre de los datos de telemetría de las solicitudes y dependencias. También puede usar una expresión regular para extraer uno o más atributos nuevos del nombre del intervalo.

Un procesador de registros puede actualizar el nombre de la telemetría de los registros. También puede usar una expresión regular para extraer uno o varios atributos nuevos del nombre del registro.

Un filtro de métricas puede filtrar las métricas para ayudar a controlar el costo de la ingesta.

Nota

Actualmente, los procesadores de telemetría solo procesan atributos de tipo cadena. No procesan atributos de tipo booleano o numérico.

Introducción

Para empezar, cree un archivo de configuración denominado applicationinsights.json. Guárdelo en el mismo directorio que applicationinsights-agent-*.jar. Use la siguiente plantilla.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        ...
      },
      {
        "type": "attribute",
        ...
      },
      {
        "type": "span",
        ...
      },
      {
        "type": "log",
        ...
      },
      {
        "type": "metric-filter",
        ...
      }
    ]
  }
}

Procesador de atributos

El procesador de atributos modifica los atributos de un span o un log. Puede admitir la posibilidad de incluir o excluir span o log. Toma una lista de acciones que se realizan en el orden especificado en el archivo de configuración. El procesador admite estas acciones:

insert
update
delete
hash
extract
mask

`insert`

La acción insert inserta un nuevo atributo en un elemento de telemetría en el que key aún no existe.

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

La acción insert requiere la siguiente configuración:

key
value o fromAttribute
action: insert

`update`

La acción update actualiza un atributo en un elemento de telemetría en el que ya existe key.

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

La acción update requiere la siguiente configuración:

key
value o fromAttribute
action: update

`delete`

La acción delete elimina un atributo de un elemento de telemetría.

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

La acción delete requiere la siguiente configuración:

key
action: delete

`hash`

La acción hash aplica un algoritmo hash (SHA1) a un valor de atributo existente.

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

La acción hash requiere la siguiente configuración:

key
action: hash

`extract`

Nota

La característica extract solo está disponible en la versión 3.0.2 y posteriores.

La acción extract extrae valores mediante una regla de expresión regular de la clave de entrada a las claves de destino especificadas en la regla. Si ya existe una clave de destino, la acción extract invalida la clave de destino. Esta acción se comporta como el valor toAttributes del procesador de intervalos, donde el atributo existente es el origen.

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

La acción extract requiere la siguiente configuración:

key
pattern
action: extract

`mask`

Nota:

La característica mask solo está disponible en la versión 3.2.5 y posteriores.

La acción mask enmascara los valores de atributo mediante una regla de expresión regular especificada en pattern y replace.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attributeName",
        "pattern": "<regular expression pattern>",
        "replace": "<replacement value>",
        "action": "mask"
      }
    ]
  }
]

La acción mask requiere la siguiente configuración:

key
pattern
replace
action: mask

pattern puede contener un grupo con nombre situado entre ?< y >:. Ejemplo: (?<userGroupName>[a-zA-Z.:\/]+)\d+? El grupo es (?<userGroupName>[a-zA-Z.:\/]+) y userGroupName es el nombre del grupo. pattern entonces puede contener el grupo con el mismo nombre colocado entre ${ y } seguido de la máscara. Ejemplo en el que la máscara es **: ${userGroupName}**.

Consulte Ejemplos de procesador de telemetría para ver ejemplos de enmascaramiento.

Criterios de inclusión y de exclusión

Los procesadores de atributos admiten criterios include y exclude opcionales. Un procesador de atributos solo se aplica a la telemetría que coincide con sus criterios include (si está disponible) y no coincide con sus criterios exclude (si está disponible).

Para configurar esta opción, en include o exclude (o ambos), especifique al menos un matchType y spanNames o attributes. La configuración include o exclude permite más de una condición especificada. Todas las condiciones especificadas deben evaluarse en true para que se produzca una coincidencia.

Campos obligatorios:
- matchType controla cómo se interpretan los elementos de las matrices spanNames y attributes. Los valores posibles son regexp y strict. Las coincidencias de expresiones regulares se realizan en todo el valor del atributo, por lo que si desea hacer coincidir un valor que contiene abc en cualquier parte de él, debe usar .*abc.*.
Campos opcionales:
- spanNames debe coincidir con al menos uno de los elementos.
- attributes especifica la lista de atributos con la que hay que coincidir. Todos estos atributos deben coincidir exactamente para que se produzca una coincidencia.

Nota

Si se especifican include y exclude, se comprobarán las propiedades include antes que las propiedades exclude.

Nota

Si la configuración include o exclude no se ha especificado spanNames, los criterios de coincidencia se aplicarán en spans y en logs.

Ejemplo de uso

"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 más información, consulte los ejemplos del procesador de telemetría.

Procesador de intervalos

El procesador de intervalos modifica el nombre del intervalo o los atributos de un intervalo en función del nombre del intervalo. Puede admitir la posibilidad de incluir o excluir intervalos.

Asignación de un nombre para un intervalo

La sección name requiere la configuración fromAttributes. Los valores de estos atributos se utilizan para crear un nuevo nombre, concatenado en el orden que la configuración especifica. El procesador cambia el nombre del intervalo solo si todos estos atributos están presentes en él.

La configuración separator es opcional. Esta configuración es una cadena y se pueden usar valores divididos.

Nota:

Si el cambio de nombre depende del procesador de atributos para modificar los atributos, asegúrese de que el procesador de intervalos se especifica después del procesador de atributos en la especificación de canalización.

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

Extracción de atributos del nombre del intervalo

En la sección toAttributes se enumeran las expresiones regulares con las que tiene que coincidir el nombre del intervalo. Extrae los atributos basados en subexpresiones.

La configuración rules es obligatoria. Esta configuración muestra las reglas que se usan para extraer valores de atributo del nombre del intervalo.

Los nombres de atributo extraídos reemplazan los valores del nombre del intervalo. Cada regla de la lista es una cadena de patrón de expresión regular (regex).

Aquí se muestra cómo los nombres de atributo extraídos reemplazan los valores:

El nombre del intervalo se comprueba con la expresión regular.
Todas las subexpresiones con nombre de la expresión regular se extraen como atributos si la expresión regular coincide.
Los atributos extraídos se agregan al intervalo.
Cada nombre de subexpresión se convierte en un nombre de atributo.
La parte que coincide con la subexpresión se convierte en el valor de atributo.
El nombre del atributo extraído reemplaza la parte coincidente en el nombre del intervalo. Si los atributos ya existen en el intervalo, se sobrescriben.

El proceso se repite para todas las reglas en el orden en que se especifican. Cada regla subsiguiente funciona en el nombre del intervalo que es la salida después de procesar la regla anterior.

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

Atributos de intervalo comunes

En esta sección se enumeran algunos atributos de intervalo comunes que los procesadores de telemetría pueden usar.

Intervalos HTTP

Atributo	Tipo	Descripción
`http.request.method` (solía ser `http.method`)	string	Método de solicitud HTTP.
`url.full` (intervalo de cliente) o `url.path` (intervalo de servidor) (solía ser `http.url`)	string	URL de solicitud HTTP completa con el formato `scheme://host[:port]/path?query[#fragment]`. Normalmente, el fragmento no se transmite a través de HTTP. Pero si el fragmento es conocido, se debe incluir.
`http.response.status_code` (solía ser `http.status_code`)	number	Código de estado de respuesta HTTP.
`network.protocol.version` (solía ser `http.flavor`)	string	Tipo de protocolo HTTP.
`user_agent.original` (solía ser `http.user_agent`)	string	Valor del encabezado User-Agent de HTTP enviado por el cliente.

Intervalos de Java Database Connectivity

En la tabla siguiente se describen los atributos que puede usar en intervalos de Java Database Connectivity (JDBC):

Attribute	Tipo	Description
`db.system`	string	Identificador del producto del sistema de administración de bases de datos (DBMS) que se va a usar. Consulte Convenciones semánticas para las operaciones de base de datos.
`db.connection_string`	cadena	Cadena de conexión que se usa para conectarse a la base de datos. Se recomienda quitar las credenciales incrustadas.
`db.user`	string	Nombre de usuario para acceder a la base de datos.
`db.name`	string	La cadena se usa para informar sobre el nombre de la base de datos a la que se va a acceder. En el caso de los comandos que cambian la base de datos, esta cadena debe establecerse en la base de datos de destino, incluso si se produce un error en el comando.
`db.statement`	string	Instrucción de base de datos que se está ejecutando.

Criterios de inclusión y de exclusión

Los procesadores de intervalos admiten criterios include y exclude opcionales. Un procesador de intervalos solo se aplica a la telemetría que coincide con sus criterios include (si está disponible) y no coincide con sus criterios exclude (si está disponible).

Para configurar esta opción, en include o exclude (o en ambos), especifique al menos un matchType y spanNames o attributes del intervalo. La configuración include o exclude permite más de una condición especificada. Todas las condiciones especificadas deben evaluarse en true para que se produzca una coincidencia.

Campos obligatorios:
- matchType controla cómo se interpretan los elementos de las matrices spanNames y attributes. Los valores posibles son regexp y strict. Las coincidencias de expresiones regulares se realizan en todo el valor del atributo, por lo que si desea hacer coincidir un valor que contiene abc en cualquier parte de él, debe usar .*abc.*.
Campos opcionales:
- spanNames debe coincidir con al menos uno de los elementos.
- attributes especifica la lista de atributos con la que hay que coincidir. Todos estos atributos deben coincidir exactamente para que se produzca una coincidencia.

Nota

Si se especifican include y exclude, se comprobarán las propiedades include antes que las propiedades exclude.

Ejemplo de uso

"processors": [
  {
    "type": "span",
    "include": {
      "matchType": "strict",
      "spanNames": [
        "spanA",
        "spanB"
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute1",
          "value": "attributeValue1"
        }
      ]
    },
    "name": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

Para más información, consulte los ejemplos del procesador de telemetría.

Procesador de registros

Nota

Los procesadores de registros están disponibles a partir de la versión 3.1.1.

El procesador de registros modifica el cuerpo del mensaje de registro o los atributos del mismo en función del cuerpo del mensaje del registro. Puede admitir la posibilidad de incluir o excluir registros.

Actualización del cuerpo del mensaje del registro

La sección body requiere la configuración fromAttributes. Los valores de estos atributos se utilizan para crear un nuevo cuerpo, concatenado en el orden que la configuración especifica. El procesador cambia el cuerpo del registro solo si todos estos atributos están presentes en él.

La configuración separator es opcional. Esta configuración es una cadena. Puede especificarlo para dividir los valores.

Nota:

Si el cambio de nombre depende del procesador de atributos para modificar los atributos, asegúrese de que el procesador de registros se especifica después del procesador de atributos en la especificación de canalización.

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

Extracción de atributos del cuerpo del mensaje de registro

En la sección toAttributes se enumeran las expresiones regulares con las que tiene que coincidir el cuerpo del mensaje del registro. Extrae los atributos basados en subexpresiones.

La configuración rules es obligatoria. Esta configuración muestra las reglas que se usan para extraer valores de atributo del cuerpo del mensaje.

Los nombres de atributo extraídos reemplazan los valores en el cuerpo del mensaje de registro. Cada regla de la lista es una cadena de patrón de expresión regular (regex).

Aquí se muestra cómo los nombres de atributo extraídos reemplazan los valores:

El cuerpo del mensaje del registro se comprueba con la expresión regular.
Todas las subexpresiones con nombre de la expresión regular se extraen como atributos si la expresión regular coincide.
Los atributos extraídos se agregan al registro.
Cada nombre de subexpresión se convierte en un nombre de atributo.
La parte que coincide con la subexpresión se convierte en el valor de atributo.
El nombre del atributo extraído reemplaza la parte coincidente en el nombre del registro. Si los atributos ya existen en el registro, se sobrescriben.

El proceso se repite para todas las reglas en el orden en que se especifican. Cada regla subsiguiente funciona en el nombre del registro que es la salida después de procesar la regla anterior.

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

Criterios de inclusión y de exclusión

Los procesadores de registros admiten criterios include y exclude opcionales. Un procesador de registros solo se aplica a la telemetría que coincide con sus criterios include (si está disponible) y no coincide con sus criterios exclude (si está disponible).

Para configurar esta opción, en include o exclude (o ambos), especifique matchType y attributes. La configuración include o exclude permite más de una condición especificada. Todas las condiciones especificadas deben evaluarse en true para que se produzca una coincidencia.

Campo obligatorio:
- matchType controla cómo se interpretan los elementos de las matrices de attributes. Los valores posibles son regexp y strict. Las coincidencias de expresiones regulares se realizan en todo el valor del atributo, por lo que si desea hacer coincidir un valor que contiene abc en cualquier parte de él, debe usar .*abc.*.
- attributes especifica la lista de atributos con la que hay que coincidir. Todos estos atributos deben coincidir exactamente para que se produzca una coincidencia.

Nota

Si se especifican include y exclude, se comprobarán las propiedades include antes que las propiedades exclude.

Nota

Los procesadores de registros no admiten spanNames.

Ejemplo de uso

"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 más información, consulte los ejemplos del procesador de telemetría.

Filtro de métricas

Nota

Los filtros de métricas están disponibles a partir de la versión 3.1.1.

Los filtros de métricas se usan para excluir algunas métricas con el fin de ayudar a controlar el costo de ingesta.

Los filtros de métricas solo admiten criterios exclude. Las métricas que coinciden con sus criterios exclude no se exportan.

Para configurar esta opción, en exclude, especifique matchType y uno o varios metricNames.

Campo obligatorio:
- matchType controla cómo se comparan los elementos de metricNames. Los valores posibles son regexp y strict. Las coincidencias de expresiones regulares se realizan en todo el valor del atributo, por lo que si desea hacer coincidir un valor que contiene abc en cualquier parte de él, debe usar .*abc.*.
- metricNames debe coincidir con al menos uno de los elementos.

Ejemplo de uso

En el ejemplo siguiente se muestra cómo excluir métricas con los nombres "metricA" y "metricB":

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "strict",
      "metricNames": [
        "metricA",
        "metricB"
      ]
    }
  }
]

En el ejemplo siguiente se muestra cómo desactivar todas las métricas, incluidas las métricas de rendimiento recopiladas automáticamente y predeterminadas, como CPU y memoria.

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "regexp",
      "metricNames": [
        ".*"
      ]
    }
  }
]

Métricas predeterminadas capturadas por el agente de Java

Nombre de métrica	Tipo de métrica	Descripción	Filtrable
`Current Thread Count`	métricas personalizadas	Consulte ThreadMXBean.getThreadCount().	sí
`Loaded Class Count`	métricas personalizadas	Consulte ClassLoadingMXBean.getLoadedClassCount().	sí
`GC Total Count`	métricas personalizadas	Suma de recuentos en todas las instancias de GarbageCollectorMXBean (diferencias desde el último informe). Consulte GarbageCollectorMXBean.getCollectionCount().	sí
`GC Total Time`	métricas personalizadas	Suma de tiempo en todas las instancias de GarbageCollectorMXBean (diferencias desde el último informe). Consulte GarbageCollectorMXBean.getCollectionTime().	sí
`Heap Memory Used (MB)`	métricas personalizadas	Consulte MemoryMXBean.getHeapMemoryUsage().getUsed().	sí
`% Of Max Heap Memory Used`	métricas personalizadas	java.lang:type=Memory/ cantidad máxima de memoria en bytes. Consulte MemoryUsage	sí
`\Processor(_Total)\% Processor Time`	métricas predeterminadas	Diferencia en los contadores de carga de CPU de todo el sistema (solo usuario y sistema) divididos por el número de procesadores lógicos en un intervalo de tiempo determinado	no
`\Process(??APP_WIN32_PROC??)\% Processor Time`	métricas predeterminadas	Consulte OperatingSystemMXBean.getProcessCpuTime() (diferencia desde la última notificación, normalizada por hora y número de CPU).	no
`\Process(??APP_WIN32_PROC??)\Private Bytes`	métricas predeterminadas	Suma de MemoryMXBean.getHeapMemoryUsage() y MemoryMXBean.getNonHeapMemoryUsage().	no
`\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec`	métricas predeterminadas	`/proc/[pid]/io` Suma de bytes leídos y escritos por el proceso (diferencia desde la última notificación). Consulte proc(5).	No
`\Memory\Available Bytes`	métricas predeterminadas	Consulte OperatingSystemMXBean.getFreePhysicalMemorySize().	no

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.

Procesadores de telemetría (versión preliminar): Azure Monitor Application Insights para Java

Terminología

Tipos de procesadores de telemetría

Introducción

Procesador de atributos

insert

update

delete

hash

extract

mask

Criterios de inclusión y de exclusión

Ejemplo de uso

Procesador de intervalos

Asignación de un nombre para un intervalo

Extracción de atributos del nombre del intervalo

Atributos de intervalo comunes

Intervalos HTTP

Intervalos de Java Database Connectivity

Criterios de inclusión y de exclusión

Ejemplo de uso

Procesador de registros

Actualización del cuerpo del mensaje del registro

Extracción de atributos del cuerpo del mensaje de registro

Criterios de inclusión y de exclusión

Ejemplo de uso

Filtro de métricas

Ejemplo de uso

Métricas predeterminadas capturadas por el agente de Java

Preguntas más frecuentes

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

Recursos adicionales

`insert`

`update`

`delete`

`hash`

`extract`

`mask`