Configuration du filtrage pour les applications d' Java

Modifier en ligne

Vous pouvez réduire le volume des données de trace pour les applications d' Java s en filtrant des intervalles spécifiques en fonction de leurs attributs. Cette fonctionnalité permet d'optimiser les coûts liés à l'ingestion des données et de se concentrer sur les traces les plus pertinentes pour vos besoins en matière de surveillance des applications.

Le filtrage basé sur les attributs est disponible pour les segments de type « HTTP » et « JDBC » dans les applications Java. Pour plus d'informations sur la réduction des données issues du traçage, consultez la section « Optimiser l'ingestion des données » sur Instana.

Options de filtrage

Modifier en ligne

Vous pouvez filtrer les traces d'application d' Java. en utilisant les méthodes suivantes :

Filtrage basé sur la méthode : pour filtrer les intervalles provenant de DynamoDB,, Redis et Kafka, voir la section « Ignorer les points d'extrémité ». Grâce à cette fonctionnalité, vous pouvez exclure des traces en fonction des noms de méthodes (tels que GET, consume, ou query) et des points de terminaison (tels que les noms de sujets Kafka ).
Filtrage basé sur les attributs des balises span : pour filtrer les balises span de type HTTP et JDBC, utilisez la méthode de filtrage basée sur les attributs des balises span. Cette fonctionnalité offre des capacités de filtrage avancées basées sur divers attributs de segment, tels que les URL, les requêtes SQL ou les méthodes de l' HTTP. Cette approche prend en charge la correspondance flexible de motifs (strict, startswith, endswith, et contains) et permet de combiner plusieurs attributs dans une seule règle.

Pour obtenir des instructions détaillées sur la configuration du filtrage basé sur les attributs de portée, consultez les sections suivantes.

Exemple de tracé de référence

Modifier en ligne

L'exemple suivant montre une trace complète sans aucun filtrage appliqué, qui sert de référence tout au long de ce document :

Filtrage basé sur les attributs de portée

Modifier en ligne

Le filtrage basé sur les attributs Span pour les applications d' Java s ne peut être configuré que via le fichier de configuration.yaml l'agent. Les variables d'environnement et les propriétés système ne sont pas prises en charge pour le filtrage de la configuration.

Remarque : les modifications de configuration sont appliquées dynamiquement sans nécessiter de redémarrage de l'application après la configuration initiale.

Configuration du filtrage

Modifier en ligne

Vous pouvez configurer des règles de filtrage pour exclure les segments HTTP et JDBC en fonction d'attributs tels que les URL, les requêtes SQL ou les méthodes HTTP.

Les règles de filtrage sont définies dans la com.instana.tracing.filter section du fichier de configuration.yaml l'agent (instanaAgentDir/etc/instana/configuration.yaml). La configuration utilise une structure de type « YAML » pour définir des règles de filtrage en fonction des attributs de span.

Pour définir des règles de filtrage, utilisez la configuration suivante :

com.instana.tracing:
  filter:
    deactivate: <boolean>
    exclude:
      - name: <string>
        attributes:
          - key: <string>
            values: [<string>, ...]
            match_type: <string>

Important : vous pouvez définir plusieurs règles de filtrage dans la exclude politique. Chaque règle peut avoir plusieurs attributs qui doivent tous correspondre pour que la règle s'applique.

Zone	Obligatoire	Description
`filter`	Obligatoire	Nœud racine pour toutes les règles de filtrage.
`deactivate`	Facultatif	Commutateur de fonctionnalité permettant de désactiver le filtrage sans supprimer les règles de filtrage configurées. Lorsque cette option est `true` activée, le filtrage est désactivé. La valeur par défaut est `false` (le filtrage reste actif).
`exclude`	Obligatoire	Politique qui contient les règles d'exclusion permettant d'exclure des segments d'une trace. Actuellement, seule la `exclude` politique est prise en charge.
`name`	Obligatoire	Nom lisible par l'utilisateur qui décrit la règle de filtrage.
`attributes`	Obligatoire	Liste des attributs span qui doivent tous correspondre pour qu'une règle s'applique.
`key`	Obligatoire	Clé d'attribut Span.
`values`	Obligatoire	Liste des valeurs à faire correspondre pour l'attribut span `key`. Un attribut correspond si l'un de ses `values` correspond. Utilisez `'*'` comme caractère générique pour faire correspondre n'importe quelle valeur pour la clé d'attribut spécifiée (utile pour filtrer en fonction de la présence d'un attribut, quelle que soit sa valeur).
`match_type`	Facultatif	Définit comment les `values` attributs span sont mis en correspondance. Valeurs valides : `strict` (par défaut), `startswith`, `endswith`, et `contains`.

Comportement de suppression

Lorsque des intervalles sont exclus par des règles de filtrage, le comportement de suppression diffère entre HTTP et JDBC :

HTTP filtrage : la suppression est appliquée par défaut. Lorsqu'une période d' HTTP s est exclue, toutes les périodes enfants et les traces en aval sont automatiquement supprimées. Aucune portée n'est générée pour les appels à la base de données, les appels à des services externes ou d'autres opérations déclenchées par la requête d' HTTP s exclue.
JDBC filtrage : la suppression n' est pas appliquée. Lorsqu'une période d' JDBC s est exclue, les périodes enfants et les opérations suivantes dans la trace continuent d'être capturées.

Important : le suppression paramètre de configuration ne peut pas être configuré. Le comportement de suppression est déterminé automatiquement en fonction du type d'intervalle.

Utilisation des caractères génériques

Vous pouvez utiliser le caractère générique "*" dans le values champ pour faire correspondre n'importe quelle valeur à un attribut span spécifique. Cela est utile lorsque vous souhaitez filtrer les spans en fonction de la présence d'un attribut, quelle que soit sa valeur. Le caractère générique peut être utilisé pour le filtrage des adresses HTTP et JDBC.

Exemple : pour exclure toutes les balises qui ont un attribut d'erreur (quel que soit le message d'erreur), utilisez la configuration suivante :

com.instana.tracing:
  filter:
    exclude:
      - name: exclude all HTTP error spans
        attributes:
          - key: http.error
            values: ["*"]
            match_type: strict
      - name: exclude all JDBC error spans
        attributes:
          - key: jdbc.error
            values: ["*"]
            match_type: strict

Ordre d'exécution des règles

Les règles de filtrage sont évaluées dans l'ordre dans lequel elles apparaissent dans la configuration. Lorsqu'une période correspond à une règle de filtrage, cette règle est appliquée et aucune autre règle n'est évaluée pour cette période. Dans la exclude politique, la première règle correspondante détermine le comportement de filtrage.

Important : classez vos règles de la plus spécifique à la plus générale afin de garantir l'application du filtrage approprié.

Exemple :

com.instana.tracing:
  filter:
    exclude:
      - name: exclude specific internal health endpoint
        attributes:
          - key: http.url
            values: [/api/internal/health]
            match_type: strict
      - name: exclude all health endpoints
        attributes:
          - key: http.url
            values: [/health]
            match_type: contains

Dans cet exemple, si une balise correspond /api/internal/healthà, la première règle s'applique. Si une portée correspond à /health mais pas /api/internal/healthà, la deuxième règle s'applique. L'ordre est important car la première règle correspondante est utilisée.

HTTP filtrage des points de terminaison

Modifier en ligne

Grâce au filtrage des points de terminaison d' HTTP, vous pouvez exclure des segments d' HTTP s en fonction d'attributs tels que l' URL, la méthode et les en-têtes. Cette fonctionnalité est prise en charge pour les frameworks d' HTTP s suivants :

Servlet : applications qui utilisent le servlet Java API
Spring Web : applications utilisant Spring MVC et Spring Boot

Important : lorsqu'une période d' HTTP s est exclue, la suppression est appliquée par défaut. Toutes les extensions enfants et les tracages en aval sont automatiquement supprimés, y compris les appels à la base de données, les appels à des services externes ou toute autre opération déclenchée par la requête HTTP exclue.

Attributs Span pour le filtrage des points de terminaison d' HTTP

Vous pouvez utiliser les attributs span suivants pour filtrer les points de terminaison d' HTTP. La colonne « Nom d'affichage de l'interface utilisateur » indique comment chaque attribut apparaît dans l'interface utilisateur d' Instana lorsque vous affichez les détails d'une portée.

Remarque importante : les noms d'affichage de l'interface utilisateur indiqués dans le tableau ci-dessous sont en anglais. Si vous utilisez l'interface utilisateur d' Instana. dans une autre langue, ces libellés sont traduits en fonction de vos paramètres linguistiques. Cependant, les clés de l'attribut « span » (utilisées dans la configuration du filtrage) restent les mêmes dans toutes les langues. Parfois, les noms affichés dans l'interface utilisateur peuvent différer du mappage présenté dans ce tableau.

Attribut span	Nom d'affichage de l'interface utilisateur	Description	Exemple de valeur	Prise en charge du filtrage
`http.url`	URL	URL ou chemin	`/api/users`	Oui
`http.method`	Méthode	Méthode HTTP	`GET`	Oui
`http.status`	Code d'état	HTTP code d'état de réponse	`200`	Limité*
`http.host`	Hôte	Nom d'hôte avec port	`localhost:8080`	Oui
`http.path`	Chemin de demande	Chemin de demande	`/api/users`	Oui
`http.path_tpl`	Modèle de chemin	Modèle ou schéma de route	`/api/users/{id}`	Oui
`http.params`	Paramètres	Chaîne de requête HTTP	`action=edit&id=5`	Oui
`http.error`	Erreur	Message d'erreur	Description de l'erreur	Limité*
`http.header.<header-name>`	En-tête	HTTP en-tête de requête	`header-value`	Oui
`http.header.<response-header-name>`	En-tête	En-tête de réponse HTTP	`header-value`	Limité*

* Prise en charge limitée du filtrage : les attributs Span qui ne sont disponibles qu'après la fin de la requête d' HTTP (tels que http.status et les en-têtes de réponse http.header.<response-header-name> ) ont des capacités de filtrage limitées. Les règles de filtrage basées sur ces attributs peuvent exclure des intervalles, mais ne peuvent pas imposer la suppression des intervalles enfants et du traçage en aval, car les valeurs des attributs ne sont pas connues au moment où la décision de suppression est prise.

Variantes d'affichage de l'interface utilisateur

Bien que les clés d'attribut span restent constantes pour la configuration du filtrage, les valeurs d'affichage réelles dans l'interface utilisateur d' Instana peuvent varier en fonction du contexte :

http.status: Affiche le code d'état accompagné d'une description lisible par l'utilisateur (par exemple, 200 – OK, 404 – Not Found, ou 500 – Internal Server Error). Lors du filtrage, utilisez uniquement la valeur numérique du code d'état.
http.error: S'affiche dans l'interface utilisateur uniquement si la valeur d'erreur est une chaîne non vide. De plus, cet attribut peut être expurgé s'il contient des données sensibles telles que définies par la configuration des données sensibles de l'outil de traçabilité de l' Java. Les erreurs vides ou expurgées n'apparaissent pas dans l'interface utilisateur.
http.params: Lorsque la chaîne de requête est vide ou vierge, l'interface utilisateur affiche <no query parameters> au lieu d'une valeur vide. Lors du filtrage, effectuez une correspondance avec la valeur réelle de la chaîne de requête ou utilisez une chaîne vide.
http.url: Affiché dans l'interface utilisateur uniquement s'il diffère de http.path. Si les deux valeurs sont identiques, seul le chemin d'accès est affiché afin d'éviter toute redondance.

Important : ces variations d'affichage n'ont aucune incidence sur le fonctionnement du filtrage. Les règles de filtrage correspondent toujours aux valeurs brutes des attributs span stockées dans le backend, et non aux valeurs formatées affichées dans l'interface utilisateur.

Exemple de configuration du filtrage des points de terminaison HTTP

L'exemple suivant montre une configuration de filtrage des points de terminaison d' HTTP :

com.instana.tracing:
  filter:
    exclude:
      - name: exclude HTTP health check endpoints
        attributes:
          - key: http.url
            values: [/health, /ping, /ready]
            match_type: endswith
      - name: exclude HTTP OPTIONS requests
        attributes:
          - key: http.method
            values: [OPTIONS]
            match_type: strict

Dans l'exemple précédent, la configuration du filtrage applique les règles suivantes :

Exclut les intervalles d' HTTP s dont l' URL e se termine par /health, /ping, ou /ready. Les intervalles enfants et le traçage en aval sont automatiquement supprimés.
Exclut les intervalles d' HTTP s avec la méthode HTTPOPTIONS. Les intervalles enfants et le traçage en aval sont automatiquement supprimés.

L'exemple suivant montre l'effet du filtrage de l' HTTP avec suppression. En comparant cette trace à la trace complète sans filtrage (Figure 1), vous pouvez voir que les appels d' HTTP s avec le paramètre author=test2 sont filtrés, ainsi que toutes leurs extensions enfants :

JDBC filtrage de portée

Modifier en ligne

Grâce au filtrage des intervalles d' JDBC, vous pouvez exclure des intervalles de base de données en fonction d'attributs tels que les instructions SQL, les chaînes de connexion et les messages d'erreur.

Important : contrairement au filtrage « HTTP », le filtrage « JDBC » n'empêche PAS le traçage en aval. Lorsqu'une période d' JDBC s est exclue, les périodes enfants et les opérations suivantes dans la trace continuent d'être capturées.

Attributs span pour le filtrage span d' JDBC

Vous pouvez utiliser les attributs span suivants pour filtrer les spans d' JDBC. La colonne « Nom d'affichage dans l'interface utilisateur » indique comment chaque attribut apparaît dans l'interface utilisateur d' Instana lors de l'affichage des détails de la portée.

Remarque : les noms affichés dans l'interface utilisateur dans le tableau suivant sont en anglais. Si vous utilisez l'interface utilisateur Instana dans une autre langue, ces libellés sont traduits en fonction de vos paramètres linguistiques, mais les clés d'attribut span (utilisées dans la configuration du filtrage) restent les mêmes dans toutes les langues.

Attribut span	Nom d'affichage de l'interface utilisateur	Description	Exemple de valeur
`jdbc.connection`	Connexion	Chaîne de connexion JDBC	`jdbc:mysql://localhost:3306/mydb`
`jdbc.statement`	Instruction	Instruction SQL	`SELECT * FROM users`
`jdbc.error`	Erreur	Message d'erreur	Description de l'erreur SQL

Variantes d'affichage de l'interface utilisateur

Tout comme les attributs d'étendue HTTP, les attributs d'étendue JDBC peuvent présenter des variations dans l'interface utilisateur d' Instana :

jdbc.error: S'affiche dans l'interface utilisateur uniquement si la valeur d'erreur est une chaîne non vide. Cet attribut peut être expurgé s'il contient des données sensibles telles que définies par la configuration des données sensibles de l'outil de traçage de l' Java. Les erreurs vides ou expurgées n'apparaissent pas dans l'interface utilisateur.
jdbc.statement: Les instructions SQL peuvent être tronquées dans l'interface utilisateur à des fins d'affichage si elles dépassent une certaine longueur, mais l'instruction complète est utilisée pour l'évaluation du filtrage.

Important : ces variations d'affichage n'ont aucune incidence sur le fonctionnement du filtrage. Les règles de filtrage sont toujours comparées aux valeurs brutes des attributs span stockées dans le backend.

Exemple de configuration du filtrage de la durée d' JDBC

L'exemple suivant montre une configuration de filtrage de portée d' JDBC :

com.instana.tracing:
  filter:
    exclude:
      - name: exclude JDBC spans for audit tables
        attributes:
          - key: jdbc.statement
            values: [audit_log, session_data]
            match_type: contains
      - name: exclude SELECT queries on MySQL database
        attributes:
          - key: jdbc.statement
            values: [SELECT]
            match_type: startswith
          - key: jdbc.connection
            values: [mysql]
            match_type: contains
      - name: exclude all JDBC error spans
        attributes:
          - key: jdbc.error
            values: ['*']
            match_type: strict

Dans l'exemple précédent, la configuration du filtrage applique les règles suivantes :

Exclut les intervalles d' JDBC s dont l'instruction SQL contient audit_log ou session_data.
Exclut les intervalles d' JDBC s avec les instructions SQL qui commencent par SELECT et les chaînes de connexion qui contiennent mysql.
Exclure toutes les balises d' JDBC qui contiennent un message d'erreur (utilisant le '*' caractère générique pour correspondre à n'importe quelle valeur d'erreur).

L'exemple suivant montre l'effet du filtrage de l' JDBC. En comparant cette trace à la trace complète sans filtrage (Figure 1), vous pouvez voir que l'instruction select book0_.id as id1_0_, book0_.author as author2_0_, book0_.title as title3_0_ from book book0_ where book0_.author=?JDBC est filtrée, supprimant ainsi 2 intervalles de la trace :

Exemple de filtrage combiné d' HTTP s et d' JDBC s

Modifier en ligne

L'exemple suivant montre comment configurer simultanément les règles de filtrage HTTP et JDBC :

com.instana.tracing:
  filter:
    exclude:
      - name: exclude HTTP health check endpoints
        attributes:
          - key: http.url
            values: [/health, /status, /metrics]
            match_type: strict
      - name: exclude JDBC queries for temporary tables
        attributes:
          - key: jdbc.statement
            values: [temp_, tmp_]
            match_type: contains

Dans cet exemple :

HTTP Les spans correspondant aux points de contrôle de santé sont exclus par suppression automatique (les spans enfants et les traces en aval sont supprimées).
JDBC Les intervalles pour les tables temporaires sont exclus sans suppression (les intervalles enfants et les traces en aval continuent d'être capturés).

Limites du filtrage

Modifier en ligne

Prise en charge des politiques : actuellement, seule la exclude politique est prise en charge. La include politique n'est pas encore disponible.
Comportement de suppression :
- HTTP Le filtrage applique la suppression par défaut (les spans enfants et les traces en aval sont supprimées).
- Le suppression paramètre de configuration ne peut pas être configuré.
Prise en charge limitée de la suppression pour certains attributs d' HTTP : les règles de filtrage basées sur des attributs de span qui ne sont connus qu'après la fin de la requête d' HTTP (tels que http.statusles en-têtes de réponse comme http.header.<response-header-name> et http.error) ne peuvent pas imposer la suppression des spans enfants et du traçage en aval. Ces attributs peuvent toujours être utilisés pour exclure la portée parent HTTP de la trace. Cependant, toutes les opérations enfants ou en aval continuent d'être capturées, ce qui peut entraîner l'apparition d'opérations sans opération parent dans l'interface utilisateur.
Les règles de filtrage basées sur l'attribut http.params span peuvent ne pas fonctionner si values celui-ci contient des secrets susceptibles d'être supprimés de l'URL HTTPURL par le traceur Java.
Les modifications apportées à la configuration du filtrage sont appliquées dynamiquement sans nécessiter de redémarrage de l'application après la configuration initiale.