Configuration des codes d'état « HTTP » et « 4xx » en tant qu'erreurs

Vous pouvez marquer comme erreurs certains codes de réponse spécifiques ou l'ensemble des codes de réponse 4xx HTTP des requêtes sortantes, ce qui permet un suivi précis des erreurs dans Instana.

Par défaut, le traceur Instana .NET ne marque un segment HTTP comme erroné que lorsque le code d'état de la réponse HTTP se situe dans la plage 5xx (500–599). HTTP 4xx Par défaut, les réponses aux appels sortants (client) ne sont pas considérées comme des erreurs, car une réponse de type « 4xx », telle que 404 Not Found, peut constituer un résultat attendu dans de nombreuses applications plutôt qu’une condition d’erreur.

Grâce à cette fonctionnalité, vous pouvez classer comme des erreurs certains codes d'état spécifiques ou l'ensemble des codes d'état de la fonction « 4xx » issus des appels sortants de l' HTTP. Instana Il les considère alors comme des opérations erronées et les inclut dans les calculs du taux d'erreur, les faisant apparaître dans les tableaux de bord et les alertes relatifs aux erreurs.

Remarque :

Cette configuration s'applique uniquement aux segments sortants (client/EXIT), par exemple aux appels effectués à l'aide de ou HttpClient HttpWebRequest. Les requêtes d' HTTP s entrantes gérées par votre application (ENTRY/server spans) ne sont pas concernées. Le fait qu'un service en aval renvoie une réponse « 4xx » ne signifie pas que le serveur traitant la requête entrante a rencontré une erreur.

Un comportement exemplaire

Tableau 1. Un comportement exemplaire
Type d'étendue	Terme de traçage	Exemple	4xx comportement	5xx comportement
CLIENT	Portée EXIT	HttpClient appel vers l' API externe	Configurable (inscription facultative)	Erreur systématique
SERVEUR	span « ENTRÉE »	Demande d' ASP.NET Core ation entrante	Jamais d'erreur	Erreur systématique

Comportement par défaut

Sans aucune configuration, le traceur applique les règles suivantes :

HTTP 1xx–4xx Codes d'état : aucune balise « span » n'est signalée comme erronée.
HTTP 5xx codes d'état : toujours signalés comme des erreurs, tant sur les segments EXIT que sur les segments ENTRY.

Ce comportement est compatible avec les versions antérieures et ne nécessite aucune modification des déploiements existants. Les options de configuration décrites dans cette rubrique ajoutent une classification supplémentaire des erreurs, en plus du comportement par défaut.

Méthodes de configuration

Les méthodes de configuration suivantes sont prises en charge; elles sont classées par ordre de priorité :

Variables d'environnement : définies au démarrage du processus; priorité maximale.
YAML fichier de configuration : chemin d'accès défini via INSTANA_CONFIG_PATH.
Configuration via un agent : fournie par l'agent « Instana » au moment de la connexion; priorité la plus faible.

Une seule méthode est exécutée pendant toute la durée de vie d'un processus. Si des variables d'environnement sont définies, les fichiers « YAML » et la configuration de l'agent sont ignorés. Pour plus d'informations, consultez la section « Priorité de configuration ».

Variables d'environnement

Configurez la classification des erreurs de HTTP 4xx à l'aide des variables d'environnement suivantes.

`INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS`

Tableau 2.`INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS` propriétés
Propriété	Valeur
Type	Liste d'entiers séparés par des virgules
Valeurs admissibles	400 à 499 uniquement. Les valeurs situées en dehors de cette plage sont ignorées.
Par défaut	(non défini)
Exemple	`401,403,429`

Marque les codes d'état répertoriés HTTP 4xx comme des erreurs sur les segments EXIT (client). Lorsque cette variable est définie, INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS est ignoré.

# Linux / macOS
export INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS=401,403,429

# Windows (PowerShell)
$env:INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS="401,403,429"

# Docker
ENV INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS=401,403,429

# Kubernetes (env section of a container spec)
- name: INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS
  value: "401,403,429"

`INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS`

Tableau 3. `INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS` propriétés
Propriété	Valeur
Type	Chaîne booléenne
Valeurs admises	`true`, `false`
Par défaut	`false`

Lorsque cette option est activée true, toutes les réponses « HTTP » 4xx (codes 400 à 499) sur les segments EXIT sont considérées comme des erreurs. Ce paramètre est ignoré lorsque INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS est également défini.

# Mark all 4xx responses on exit spans as errors
export INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS=true

YAML fichier de configuration

Si vous utilisez déjà un fichier de configuration « Instana » (défini via la variable d'environnement INSTANA_CONFIG_PATH ), vous pouvez y ajouter des paramètres de classification des erreurs « HTTP » en plus d'autres paramètres de configuration, tels que le filtrage des spans.

Remarque :

YAML La configuration est ignorée si l'une ou l'autre des variables d'environnement INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS ou est définie.

Marquer certains codes d' 4xx s comme des erreurs

com.instana.tracing:
  http:
    exit:
      classify-as-errors:
        - 401
        - 403
        - 429

Marquer tous les codes « 4xx » comme des erreurs

com.instana.tracing:
  http:
    exit:
      classify-all-4xx-as-errors: true

Ordre de priorité lorsque les deux clés de configuration sont définies

Lorsque les deux clés sont présentes, classify-as-errors a la priorité.

com.instana.tracing:
  http:
    exit:
      classify-all-4xx-as-errors: true   # ignored — classify-as-errors is non-empty
      classify-as-errors:
        - 401
        - 403

Formats d' YAML s pris en charge

Tableau 4. Formats YAML pris en charge
Format	Exemple
Liste noire (suggestion)	`classify-as-errors:` avec les `- 401` éléments suivants
Tableau en ligne	`classify-as-errors: [401, 403, 429]`
Variante de la clé racine	`com.instana.tracing:` ou `tracing:`

Configuration basée sur des agents

L'agent « Instana » peut fournir une configuration de classification des erreurs « HTTP » dans le cadre de sa réponse de découverte. Le traceur lit automatiquement cette configuration lors de sa première connexion à l'agent. Aucune configuration supplémentaire n'est requise.

La configuration par agent utilise la même structure de clés que le fichier « YAML ». Il s'agit de la source ayant la priorité la plus faible; elle est ignorée sans avertissement si des variables d'environnement sont déjà définies.

Remarque :

La configuration de l'agent est appliquée une fois que l'application a démarré et s'est connectée à l'agent. Au démarrage, il peut arriver que la configuration de l'agent ne soit pas encore active pendant un court instant. Dans les environnements où le temps est un facteur critique, utilisez plutôt des variables d'environnement.

Ordre de priorité des paramètres de configuration

Lorsque plusieurs sources de configuration sont présentes, l'ordre de priorité suivant s'applique :

Environment Variables  >  YAML file  >  Agent config  >  Default (4xx not error)

Une fois détectées au démarrage, les variables d'environnement sont figées pour toute la durée de vie du processus. YAML et les configurations des agents sont contournées de manière permanente.

Priorité au sein d'une même source : quelle que soit la source de configuration, lorsque les deux clés sont présentes, a classify-as-errors toujours la priorité sur classify-all-4xx-as-errors.

Exemples de configuration

Exemple 1 : Ne signaler comme erreur que le code 401 « Accès non autorisé »

Utilisez cette configuration lorsque votre application considère qu'un code 404 est normal, mais qu'un code 401 indique toujours une erreur de configuration du client :

export INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS=401

Exemple 2 : Considérer les échecs d'authentification et de limitation du débit comme des erreurs

export INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS=401,403,429

Exemple 3 : Marquer toutes les instructions « 4xx » comme des erreurs dans un environnement strict

export INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS=true

Exemple 4 : YAML avec des codes spécifiques

com.instana.tracing:
  http:
    exit:
      classify-as-errors:
        - 401
        - 403

Exemple 5 : Déploiement d' Kubernetes

env:
  - name: INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS
    value: "401,403,429"

Meilleures pratiques

Tenez compte des bonnes pratiques suivantes lorsque vous configurez HTTP pour que les codes d'état 4xx soient considérés comme des erreurs.

Utilisez des codes spécifiques plutôt que de regrouper tous les codes d'état d' 4xx

Ce paramètre classify-all-4xx-as-errors: true marque toutes les réponses de type « 4xx » comme des erreurs, y compris les codes tels que 404 Not Found et 409 Conflict qui sont souvent attendus et inoffensifs. Ce paramètre peut faire grimper le nombre d'erreurs et déclencher de fausses alertes. Privilégiez la liste des codes spécifiques qui indiquent réellement des défaillances imprévues dans le contexte de votre application.

Commencez par une approche restreinte, puis élargissez-la si nécessaire

Commencez par ne marquer que les codes les plus clairement associés à des erreurs (généralement 401, 403, 429) et observez l'effet sur vos tableaux de bord avant d'ajouter d'autres codes. Une augmentation soudaine du taux d'erreur peut compliquer l'identification des véritables régressions.

Utilisation des variables d'environnement dans les conteneurs et l' Kubernetes

Les variables d'environnement constituent la méthode de configuration la plus fiable dans les environnements conteneurisés. Elles sont appliquées au démarrage, apparaissent dans les spécifications des pods et ne peuvent pas être contournées en cas de problèmes de connectivité de l'agent. N'utilisez la configuration « YAML » ou la configuration par agent que lorsque la gestion centralisée de nombreux services est nécessaire.

Ne définissez pas à la fois une variable d'environnement et YAML pour le même paramètre

Lorsque les deux sont présentes, la variable d'environnement prévaut et la valeur de ` YAML ` est ignorée sans message d'avertissement. Pour éviter toute confusion, utilisez une seule méthode de configuration pour chaque déploiement et documentez-la.

Évitez d'utiliser la fonction « classer tout » dans les services partagés ou multi-locataires

Dans le cas de services utilisés par plusieurs équipes ou clients, certains codes d' 4xx peuvent être valables pour certains appelants. Des listes de codes spécifiques permettent un signalement prévisible et cohérent des erreurs, sans perturber les appelants pour lesquels ces codes sont prévus.

Traitement des incidents

Utilisez les informations de dépannage suivantes pour diagnostiquer et résoudre les problèmes courants liés à la classification des erreurs « HTTP » ( 4xx ).

4xx les intervalles ne sont pas signalés comme des erreurs après la configuration

Vérifiez que la configuration est chargée une seule fois au démarrage (variables d'environnement et YAML ) ou lors de la première connexion de l'agent. Vérifiez que les variables d'environnement sont bien définies avant le démarrage du processus.
Vérifiez que la variable d'environnement est correctement définie. Exécutez printenv | grep INSTANA_TRACING ( Linux ) ou Get-ChildItem Env: | Where-Object Name -like "INSTANA_TRACING*" ( PowerShell ) dans l'environnement du processus.
Vérifiez la plage des codes d'état. Seuls les nombres entiers compris entre 400 et 499 sont acceptés. Les valeurs telles que 500, 200, ou les chaînes de caractères non numériques sont ignorées sans message d'erreur, mais un avertissement est consigné.
Vérifiez bien qu'il s'agit bien d'une balise EXIT et non d'une balise ENTRY.

Le nombre d'erreurs est anormalement élevé après l'activation de l'option « classify-all »

Ce paramètre INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS=true marque toutes les réponses de type « 4xx » comme des erreurs, y compris les codes tels que 404 ou 409 qui pourraient normalement apparaître dans votre application. Passez en mode INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS avec une liste spécifique de codes pour réduire le bruit.

YAML la configuration n'est pas prise en compte

Vérifiez que INSTANA_CONFIG_PATH pointe vers un fichier qui existe et qui est accessible en lecture par l'utilisateur du processus.
Assurez-vous qu'aucune des variables d'environnement INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS ni INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS ne soit définie. Elles redéfinissent la méthode ` YAML ` sans afficher de message.
Vérifiez que les noms de clés de l' YAML t comportent des tirets (-), et non des traits de soulignement : classify-as-errors, et non classify_as_errors.
Vérifiez les retraits. YAML est sensible aux retraits. http doit être un enfant de com.instana.tracing (ou tracing), et exit doit être un enfant de http.

La configuration de l'agent n'est pas appliquée

La configuration de l'agent n'est appliquée qu'une fois que le traceur s'est connecté à l'agent. Si l'agent n'est pas disponible au démarrage, il se peut que sa configuration ne soit pas prise en compte. Utilisez des variables d'environnement pour garantir la configuration au démarrage.

Vérifiez qu'aucune variable d'environnement susceptible de remplacer la configuration de l'agent n'est définie :

printenv | grep INSTANA_TRACING

La configuration semble se réinitialiser à chaque redémarrage

Dans certains environnements, les variables d'environnement définies lors d'une session de shell ne sont pas héritées par les processus enfants. Définissez-les dans la définition du service système, dans le fichier ` Docker Compose `, dans la spécification du pod ` Kubernetes ` ou dans le script de démarrage de l'application afin de garantir leur persistance après chaque redémarrage.

Compte de référence

Les informations de référence suivantes présentent un résumé des variables d'environnement, des clés de la base de données « YAML » et des règles de validation.

Variables d'environnement

Tableau 5. Variables d'environnement
Variables	Type	Par défaut	Description
`INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS`	Nombres entiers séparés par des virgules	(non défini)	Liste des codes « 4xx » à considérer comme des erreurs sur les segments EXIT. Les valeurs situées en dehors de la plage 400–499 sont ignorées. Prend le pas sur `classify-all`.
`INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS`	`true` ou `false`	`false`	Lorsque `true`, toutes les réponses comprises entre 400 et 499 sont considérées comme des erreurs dans les intervalles EXIT. Ignoré lorsque `classify-as-errors` est défini.
`INSTANA_CONFIG_PATH`	Chemin de fichier	Non défini	Chemin d'accès absolu au fichier de configuration d' YAML. Partagé avec le filtrage par intervalle et d'autres fonctionnalités du traceur.

YAML touches

Tableau 6. YAML touches
Chemin de clé	Type	Description
`com.instana.tracing.http.exit.classify-as-errors`	Liste d'entiers	Liste des codes d'état « 4xx » à considérer comme des erreurs sur les segments EXIT.
`com.instana.tracing.http.exit.classify-all-4xx-as-errors`	Booléen	Dans ce cas `true`, les 400 à 499 réponses sont toutes considérées comme des erreurs au niveau des segments EXIT.

Règles de validation

Les valeurs de classify-as-errors doivent être des nombres entiers compris entre 400 et 499.
Toute valeur ne se situant pas dans cette plage est ignorée et un avertissement est consigné dans le journal de traçage.
Les valeurs non entières sont ignorées et un avertissement est consigné dans le journal de traçage.
Lorsque les deux clés se trouvent au même niveau de configuration, classify-as-errors a la priorité.
5xx Les codes d'état (500 à 599) sont toujours considérés comme des erreurs et ne peuvent pas être désactivés.
Les plages ENTRY (serveur) ne sont jamais affectées, quelle que soit la configuration.