Partager via

Processeurs de télémétrie (préversion) – Azure Monitor Application Insights pour Java

  • Article

Notes

La fonctionnalité de processeurs de télémétrie est désignée comme étant en préversion, car nous ne pouvons pas garantir la compatibilité descendante d’une version à l’autre en raison de l’état expérimental des conventions sémantiques d’attributs. Toutefois, la fonctionnalité a été testée et est prise en charge en production.

Application Insights Java 3.x peut traiter des données de télémétrie avant leur exportation.

Voici quelques cas d’utilisation :

  • Masquer des données sensibles.
  • Ajouter de manière conditionnelle des dimensions personnalisées.
  • Mettre à jour le nom de l’étendue, qui est utilisé pour agréger des données de télémétrie similaires dans le portail Azure.
  • Supprimer les attributs d’étendue spécifiques pour contrôler les coûts d’ingestion.
  • Filtrer certaines métriques pour contrôler les coûts d’ingestion.

Notes

Si vous envisagez d’annuler des étendues spécifiques (entières) pour contrôler le coût d’ingestion, consultez Remplacements d’échantillonnage.

Terminologie

Avant d’en savoir plus sur les processeurs de télémétrie, vous devez comprendre les termes étendue et journal.

Une étendue est un type de télémétrie qui représente un des éléments suivants :

  • Une requête entrante.
  • Une dépendance sortante (par exemple, un appel distant à un autre service).
  • Une dépendance « in-process » (par exemple, une tâche effectuée par les sous-composants du service).

Un journal est un type de télémétrie qui représente :

  • des données de journal capturées à partir de Log4j, Logback et java.util.logging

Pour les processeurs de télémétrie, ces composants d’étendue/de journal sont importants :

  • Nom
  • Corps
  • Attributs

Le nom de l’étendue est l’affichage principal utilisé pour les requêtes et les dépendances dans le portail Azure. Les attributs d’étendue représentent à la fois les propriétés standard et personnalisées d’une requête ou d’une dépendance donnée.

Le message ou le corps de la trace est l’affichage principal des journaux dans le portail Azure. Les attributs de journal représentent à la fois les propriétés standard et personnalisées d’un journal donné.

Types de processeurs de télémétrie

Actuellement, les quatre types de processeurs de télémétrie sont

  • Processeurs d’attributs
  • Processeurs d’étendue
  • Processeurs de journaux
  • Filtres de métriques

Un processeur d’attributs peut insérer, mettre à jour, supprimer ou hacher les attributs d’un élément de télémétrie (span ou log). Il peut également utiliser une expression régulière pour extraire un ou plusieurs nouveaux attributs d’un attribut existant.

Un processeur d’étendues peut mettre à jour le nom de la télémétrie des requêtes et des dépendances. Il peut également utiliser une expression régulière pour extraire un ou plusieurs nouveaux attributs du nom de l’étendue.

Un processeur de journaux peut mettre à jour le nom de la télémétrie des journaux. Il peut également utiliser une expression régulière pour extraire un ou plusieurs nouveaux attributs du nom de journal.

Un filtre de métriques peut filtrer les métriques pour vous aider à contrôler le coût d’ingestion.

Notes

Actuellement, les processeurs de télémétrie traitent uniquement les attributs de type chaîne. Ils ne traitent pas les attributs de type booléen ou nombre.

Prise en main

Pour commencer, créez un fichier de configuration nommé applicationinsights.json. Enregistrez-le dans le même répertoire que le fichier applicationinsights-agent-*.jar. Utilisez le modèle suivant.

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

Processeur d’attributs

Le processeur d’attributs modifie les attributs d’un élément span ou log. Il peut prendre en charge la possibilité d’inclure ou d’exclure span ou log. Il prend une liste d’actions qui sont exécutées dans l’ordre spécifié par le fichier de configuration. Le processeur prend en charge les actions suivantes :

  • insert
  • update
  • delete
  • hash
  • extract
  • mask

insert

L’action insert insère un nouvel attribut dans l’élément de télémétrie où la key n’existe pas encore.

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

L’action insert nécessite les paramètres suivants :

  • key
  • value ou fromAttribute
  • action: insert

update

L’action update met à jour un attribut dans un élément de télémétrie où la key existe déjà.

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

L’action update nécessite les paramètres suivants :

  • key
  • value ou fromAttribute
  • action: update

delete

L’action delete supprime un attribut d’un élément de télémétrie.

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

L’action delete nécessite les paramètres suivants :

  • key
  • action: delete

hash

L’action hash hache (SHA1) une valeur d’attribut existante.

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

L’action hash nécessite les paramètres suivants :

  • key
  • action: hash

extract

Notes

La fonctionnalité extract est disponible uniquement dans la version 3.0.2 et les versions ultérieures.

L’action extract extrait des valeurs en suivant une règle d’expression régulière de la clé d’entrée vers les clés cibles spécifiées dans la règle. Si une clé cible existe déjà, l’action extract remplace la clé cible. Cette action se comporte comme le paramètre toAttributes du processeur d’étendue, où l’attribut existant est la source.

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

L’action extract nécessite les paramètres suivants :

  • key
  • pattern
  • action: extract

mask

Remarque

La fonctionnalité mask est disponible uniquement dans la version 3.2.5 et les versions ultérieures.

L’action mask masque les valeurs d’attribut à l’aide d’une règle d’expression régulière spécifiée dans pattern et replace.

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

L’action mask nécessite les paramètres suivants :

  • key
  • pattern
  • replace
  • action: mask

pattern peut contenir un groupe nommé placé entre ?< et >:. Exemple : (?<userGroupName>[a-zA-Z.:\/]+)\d+ ? Le groupe est (?<userGroupName>[a-zA-Z.:\/]+) et le nom du groupe est userGroupName. pattern peut ensuite contenir le même groupe nommé placé entre ${ et } suivi du masque. Exemple dans lequel le masque est ** : ${userGroupName}**.

Pour obtenir des exemples de masquage, consultez Exemples de processeur de télémétrie.

Inclure des critères et exclure des critères

Les processeurs d’attributs prennent en charge les critères include et exclude facultatifs. Un processeur d’attributs est appliqué uniquement à la télémétrie qui correspond à ses critères include (si disponibles) et qui ne correspond pas à ses critères exclude (si disponibles).

Pour configurer cette option, sous include ou exclude (ou les deux), spécifiez au moins un matchType et spanNames ou attributes. La configuration include ou exclude autorise plusieurs conditions spécifiées. Pour qu’une correspondance soit établie, toutes les conditions spécifiées doivent prendre la valeur true.

  • Champs obligatoires :

    • matchType contrôle la façon dont les éléments des tableaux spanNames et attributes sont interprétés. Les valeurs possibles sont regexp et strict. Les correspondances des expressions régulières sont effectuées par rapport à la valeur entière de l’attribut. Par conséquent, si vous souhaitez faire correspondre une valeur contenant abc n’importe où dans celle-ci, vous devez utiliser .*abc.*.

  • Champs facultatifs :

    • spanNames doit correspondre au moins à l’un des éléments.
    • attributes spécifie la liste des attributs par rapport auxquels établir une correspondance. Tous ces attributs doivent correspondre exactement pour qu’une correspondance soit établie.

Notes

Si les attributs include et exclude sont tous deux spécifiés, les propriétés include sont vérifiées avant les propriétés exclude.

Notes

Si la configuration include ou exclude n’a pas de spanNames spécifiés, le critère de correspondance est appliqué à la fois sur les spans et les logs.

Exemple d’utilisation

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

Pour plus d’informations, consultez Exemples de processeurs de télémétrie.

Processeur d’étendue

Le processeur d’étendue modifie le nom ou les attributs d’une étendue en fonction de son nom. Il peut prendre en charge la possibilité d’inclure ou d’exclure des étendues.

Nommer une étendue

La name section requiert le paramètre fromAttributes. Les valeurs de ces attributs sont utilisées pour créer un nouveau nom, concaténées dans l’ordre spécifié par la configuration. Le processeur ne modifie le nom de l’étendue que si tous ces attributs sont présents sur l’étendue.

Le paramètre separator est facultatif. Ce paramètre est une chaîne et vous pouvez utiliser des valeurs fractionnées.

Remarque

Si le changement de nom dépend du processeur d’attributs pour modifier les attributs, assurez-vous que le processeur d’étendue est spécifié après le processeur d’attributs dans la spécification du pipeline.

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

Extraire des attributs du nom d’étendue

La section toAttributes répertorie les expressions régulières à mettre en correspondance avec le nom de l’étendue. Elle extrait des attributs en fonction des sous-expressions.

Le paramètre rules est obligatoire. Ce paramètre répertorie les règles utilisées pour extraire des valeurs d’attribut du nom d’étendue.

Les noms d’attributs extraits remplacent les valeurs dans le nom de l’étendue. Chaque règle de la liste est une chaîne de modèle d’expression régulière (regex).

Voici comment les noms d’attributs extraits remplacent les valeurs :

  1. Le nom d’étendue est vérifié par rapport à l’expression régulière.
  2. Si l’expression régulière correspond, toutes les sous-expressions nommées de l’expression régulière sont extraites en tant qu’attributs.
  3. Les attributs extraits sont ajoutés à l’étendue.
  4. Chaque nom de sous-expression devient un nom d’attribut.
  5. La portion correspondante de la sous-expression devient la valeur de l’attribut.
  6. Le nom d’attribut extrait remplace la portion correspondante dans le nom de l’étendue. Si les attributs existent déjà dans l’étendue, ils sont remplacés.

Le processus est répété pour toutes les règles dans l’ordre spécifié. Chaque règle subséquente fonctionne sur le nom d’étendue qui est la sortie de la règle précédente.

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

Attributs d’étendue courants

Cette section répertorie certains attributs d’étendue courants que les processeurs de télémétrie peuvent utiliser.

Étendues HTTP

Attribut Type Description
http.request.method (anciennement http.method) string Méthode de requête HTTP.
url.full (étendue de client) ou url.path (étendue de serveur) (anciennement http.url) string URL complète de la requête HTTP sous la forme scheme://host[:port]/path?query[#fragment]. Le fragment n’est généralement pas transmis via HTTP. Toutefois, si le fragment est connu, il doit être inclus.
http.response.status_code (anciennement http.status_code) number Code de statut de la réponse HTTP.
network.protocol.version (anciennement http.flavor) string Type de protocole HTTP.
user_agent.original (anciennement http.user_agent) string Valeur de l’en-tête HTTP User-Agent envoyé par le client.

Étendues Java Database Connectivity

Le tableau suivant décrit les attributs que vous pouvez utiliser dans les étendues JDBC (Java Database Connectivity) :

Attribut Type Description
db.system string Identificateur du produit SGBD (système de gestion de base de données) utilisé. Consultez les Conventions sémantiques pour les opérations de base de données.
db.connection_string string Chaîne de connexion utilisée pour se connecter à la base de données. Nous vous recommandons de supprimer les informations d’identification incorporées.
db.user string Nom d’utilisateur utilisé pour accéder à la base de données.
db.name string Chaîne utilisée pour signaler le nom de la base de données qui fait l’objet de l’accès. Dans les commandes qui changent de base de données, cette chaîne doit être définie sur la base de données cible, même en cas d’échec de la commande.
db.statement string Instruction de base de données en cours d’exécution.

Inclure des critères et exclure des critères

Les processeurs d’étendues prennent en charge les critères include et exclude facultatifs. Un processeur d’étendues est appliqué uniquement à la télémétrie qui correspond à ses critères include (si disponibles) et qui ne correspond pas à ses critères exclude (si disponibles).

Pour configurer cette option, sous include ou exclude (ou les deux), spécifiez au moins un matchType et spanNames ou l’étendue attributes. La configuration include ou exclude autorise plusieurs conditions spécifiées. Pour qu’une correspondance soit établie, toutes les conditions spécifiées doivent prendre la valeur true.

  • Champs obligatoires :

    • matchType contrôle la façon dont les éléments des tableaux spanNames et attributes sont interprétés. Les valeurs possibles sont regexp et strict. Les correspondances des expressions régulières sont effectuées par rapport à la valeur entière de l’attribut. Par conséquent, si vous souhaitez faire correspondre une valeur contenant abc n’importe où dans celle-ci, vous devez utiliser .*abc.*.

  • Champs facultatifs :

    • spanNames doit correspondre au moins à l’un des éléments.
    • attributes spécifie la liste des attributs par rapport auxquels établir une correspondance. Tous ces attributs doivent correspondre exactement pour qu’une correspondance soit établie.

Notes

Si les attributs include et exclude sont tous deux spécifiés, les propriétés include sont vérifiées avant les propriétés exclude.

Exemple d’utilisation

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

Pour plus d’informations, consultez Exemples de processeurs de télémétrie.

Processeur de journaux

Notes

Les processeurs de journaux sont disponibles à partir de la version 3.1.1.

Le processeur de journaux modifie soit le corps du message du journal, soit les attributs d’un journal en fonction du corps du message du journal. Il peut prendre en charge la possibilité d’inclure ou d’exclure des journaux.

Mettre à jour le corps du message du journal

La body section requiert le paramètre fromAttributes. Les valeurs de ces attributs sont utilisées pour créer un nouveau corps, concaténées dans l’ordre spécifié par la configuration. Le processeur change le corps du journal uniquement si tous ces attributs sont présents dans le journal.

Le paramètre separator est facultatif. Ce paramètre est une chaîne. Vous pouvez le spécifier pour fractionner les valeurs.

Remarque

Si le changement de nom dépend du processeur d’attributs pour modifier les attributs, assurez-vous que le processeur de journaux est spécifié après le processeur d’attributs dans la spécification du pipeline.

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

Extraire les attributs du corps du message du journal

La section toAttributes répertorie les expressions régulières à faire correspondre au corps du message du journal. Elle extrait des attributs en fonction des sous-expressions.

Le paramètre rules est obligatoire. Ce paramètre répertorie les règles utilisées pour extraire des valeurs d’attribut du corps.

Les noms d’attributs extraits remplacent les valeurs dans le corps du message du journal. Chaque règle de la liste est une chaîne de modèle d’expression régulière (regex).

Voici comment les noms d’attributs extraits remplacent les valeurs :

  1. Le corps du message du journal est comparé à l’expression régulière.
  2. Si l’expression régulière correspond, toutes les sous-expressions nommées de l’expression régulière sont extraites en tant qu’attributs.
  3. Les attributs extraits sont ajoutés au journal.
  4. Chaque nom de sous-expression devient un nom d’attribut.
  5. La portion correspondante de la sous-expression devient la valeur de l’attribut.
  6. Le nom d’attribut extrait remplace la partie correspondante dans le nom du journal. Si les attributs existent déjà dans le journal, ils sont remplacés.

Le processus est répété pour toutes les règles dans l’ordre spécifié. Chaque règle subséquente fonctionne sur le nom de journal qui est le résultat de la règle précédente.

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

Inclure des critères et exclure des critères

Les processeurs de journaux prennent en charge les critères include et exclude facultatifs. Un processeur de journaux est appliqué uniquement à la télémétrie qui correspond à ses critères include (si disponibles) et qui ne correspond pas à ses critères exclude (si disponibles).

Pour configurer cette option, sous include ou exclude (ou les deux), spécifiez matchType et attributes. La configuration include ou exclude autorise plusieurs conditions spécifiées. Pour qu’une correspondance soit établie, toutes les conditions spécifiées doivent prendre la valeur true.

  • Champ obligatoire :
    • matchType contrôle la façon dont les éléments des tableaux attributes sont interprétés. Les valeurs possibles sont regexp et strict. Les correspondances des expressions régulières sont effectuées par rapport à la valeur entière de l’attribut. Par conséquent, si vous souhaitez faire correspondre une valeur contenant abc n’importe où dans celle-ci, vous devez utiliser .*abc.*.
    • attributes spécifie la liste des attributs par rapport auxquels établir une correspondance. Tous ces attributs doivent correspondre exactement pour qu’une correspondance soit établie.

Notes

Si les attributs include et exclude sont tous deux spécifiés, les propriétés include sont vérifiées avant les propriétés exclude.

Notes

Les processeurs de journaux ne prennent pas en charge spanNames.

Exemple d’utilisation

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

Pour plus d’informations, consultez Exemples de processeurs de télémétrie.

Filtre de métriques

Notes

Les filtres de métriques sont disponibles à partir de la version 3.1.1.

Les filtres de métriques sont utilisés pour exclure certaines métriques afin de contrôler le coût d’ingestion.

Les filtres de métriques prennent en charge uniquement les critères exclude. Les métriques qui correspondent à ses critères exclude ne sont pas exportées.

Pour configurer cette option, sous exclude, spécifiez le matchType d’un ou de plusieurs metricNames.

  • Champ obligatoire :
    • matchType contrôle la façon dont les éléments dans metricNames sont mis en correspondance. Les valeurs possibles sont regexp et strict. Les correspondances des expressions régulières sont effectuées par rapport à la valeur entière de l’attribut. Par conséquent, si vous souhaitez faire correspondre une valeur contenant abc n’importe où dans celle-ci, vous devez utiliser .*abc.*.
    • metricNames doit correspondre au moins à l’un des éléments.

Exemple d’utilisation

L’exemple suivant montre comment exclure des métriques nommées « metricA » et « metricB » :

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

L’exemple suivant montre comment désactiver toutes les métriques, y compris les métriques de performances collectées automatiquement par défaut, comme le processeur et la mémoire.

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

Métriques par défaut capturées par l’agent Java

Nom de métrique Type de métrique Description Filtrable
Current Thread Count métriques personnalisées Voir ThreadMXBean.getThreadCount(). Oui
Loaded Class Count métriques personnalisées Voir ClassLoadingMXBean.getLoadedClassCount(). Oui
GC Total Count métriques personnalisées Somme des nombres sur toutes les instances GarbageCollectorMXBean (diff depuis le dernier rapport). Voir GarbageCollectorMXBean.getCollectionCount(). Oui
GC Total Time métriques personnalisées Somme du temps entre toutes les instances GarbageCollectorMXBean (diff depuis le dernier rapport). Voir GarbageCollectorMXBean.getCollectionTime(). Oui
Heap Memory Used (MB) métriques personnalisées Voir MemoryMXBean.getHeapMemoryUsage().getUsed(). Oui
% Of Max Heap Memory Used métriques personnalisées java.lang:type=Memory : quantité maximale de mémoire en octets. Voir MemoryUsage. Oui
\Processor(_Total)\% Processor Time métriques par défaut Différence entre les compteurs du nombre de cycles de la charge du processeur à l’échelle du système (utilisateur et système uniquement) divisée par le nombre de processeurs logiques dans un intervalle de temps donné non
\Process(??APP_WIN32_PROC??)\% Processor Time métriques par défaut Voir OperatingSystemMXBean.getProcessCpuTime() (différence depuis le dernier rapport, normalisée par heure et nombre de processeurs). Non
\Process(??APP_WIN32_PROC??)\Private Bytes métriques par défaut Somme de MemoryMXBean.getHeapMemoryUsage() et MemoryMXBean.getNonHeapMemoryUsage(). Non
\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec métriques par défaut /proc/[pid]/io Somme d’octets lus et écrits par le processus (différence depuis le dernier rapport). Voir proc(5). Non
\Memory\Available Bytes métriques par défaut Voir OperatingSystemMXBean.getFreePhysicalMemorySize(). non

Forum aux questions

Pourquoi le processeur de journaux ne traite-t-il pas les fichiers journaux en utilisant TelemetryClient.trackTrace() ?

TelemetryClient.trackTrace() fait partie du pont du SDK classique Application Insights, et les processeurs de journaux fonctionnent uniquement avec la nouvelle instrumentation basée sur OpenTelemetry.