Configuration des traces de pile pour .NET Framework

Par défaut, l'outil « .NET Framework Tracer » capture les traces de pile de tous les segments avec une profondeur de trace par défaut de 35 cadres. Vous pouvez utiliser la configuration de la trace de pile pour contrôler le volume de données de trace collectées et traitées par Instana. Utilisez la configuration des traces de pile pour personnaliser l'outil « .NET Framework Tracer » afin de ne collecter les traces de pile que pour les segments présentant des erreurs, de désactiver complètement la collecte des traces de pile et de contrôler la profondeur des traces de pile.

Important :
Avec l'introduction de la configuration des traces de pile, la variable d'environnement INSTANA_OMIT_CALLBACK est obsolète dans le traceur.NET Framework 1.321.2.

Méthodes de configuration

.NET Framework Tracer prend en charge les méthodes suivantes pour configurer les traces de pile :

Option 1 : Configuration des traces de pile via des variables d'environnement

Vous pouvez configurer le niveau et la longueur de la trace de pile à l'aide des variables d'environnement INSTANA_STACK_TRACE_LENGTH INSTANA_STACK_TRACE et.

Tableau 1. Variables d'environnement de la trace de pile
Variable d"environnement Description Valeurs prises en charge
INSTANA_STACK_TRACE Niveau de trace de pile all (par défaut) : collecter les traces de pile pour tous les segments; error: collecter les traces de pile uniquement pour les segments EXIT présentant des erreurs. Les traces de pile ne sont pas collectées pour les segments ENTRY (par exemple, les segments de requête de type « ASP.NET »), car ils ne contiennent généralement que des trames au niveau du framework qui présentent peu d'intérêt pour le diagnostic; none: Désactiver la collecte des traces de pile. Quel que soit le mode configuré, les segments d’entrée et de sortie de la fonction « HTTP » qui génèrent une erreur (span.ec=1) renvoient toujours une trace de pile.
INSTANA_STACK_TRACE_LENGTH Profondeur de la trace de pile 1 – 200 (par défaut : 35)

Pour ne collecter les traces de pile que pour les segments présentant des erreurs, avec une profondeur de trace de pile de 10, définissez les variables d'environnement suivantes :

INSTANA_STACK_TRACE=error
INSTANA_STACK_TRACE_LENGTH=10

Option 2 : Configuration des traces de pile via un fichier de configuration « YAML »

Pour une configuration structurée et gérée par contrôle de version, utilisez un fichier de configuration de type « YAML ».

Pour configurer les traces de pile via un fichier de configuration « YAML », procédez comme suit :

  1. Créez un fichier de configuration YAML, par exemple, instana-config.yaml, et ajoutez la configuration de la trace de pile dans la section tracing.global . Vous pouvez également définir des règles de remplacement spécifiques à chaque technologie sous tracing.<technology>:
    tracing:
  global:
    stack-trace: error
    stack-trace-length: 12
  aspnet:
    stack-trace: all
    stack-trace-length: 20

    Cette section tracing.global s'applique à toutes les portées. Utilisez une section tracing.<technology> pour remplacer les paramètres globaux pour une technologie spécifique (par exemple, aspnet, sqlserver). Les paramètres propres à chaque technologie prévalent sur les paramètres globaux tracing.global.

  2. Définissez la variable d'environnement INSTANA_CONFIG_PATH avec le chemin absolu du fichier « YAML » :
    INSTANA_CONFIG_PATH=C:\path\to\instana-config.yaml

Pour plus d'informations sur les champs et les valeurs pris en charge, consultez la référence de configuration de la trace de pile.

Option 3 : Configuration des traces de pile via la configuration de l'agent « Instana »

Pour configurer les traces de pile via l'agent « Instana », créez ou modifiez la section com.instana.tracing dans le fichier configuration.yaml de l'agent (<instana-agent>/etc/instana/configuration.yaml).

Pour collecter les traces de pile de tous les segments avec une profondeur de trace de 4, ajoutez l'extrait de code suivant au fichier configuration.yaml de l'agent :

com.instana.tracing:
  global:
    stack-trace: all
    stack-trace-length: 4
Remarque :
Lorsque vous utilisez un fichier de configuration de type « YAML » (option 2), utilisez la clé tracing (obligatoire). La clé com.instana.tracing est également acceptée à des fins de compatibilité ascendante, mais elle déclenche un avertissement indiquant qu'elle est obsolète.
Remarque :
.NET Framework Tracer récupère automatiquement la configuration depuis l'agent au démarrage et vérifie régulièrement la présence de mises à jour. Les modifications de configuration ultérieures prennent effet sans qu'il soit nécessaire de redémarrer l'application «.NET Framework ».

Pour plus d'informations sur les champs et les valeurs pris en charge, consultez la référence de configuration de la trace de pile.

Référence de configuration de la trace de pile

Utilisez la syntaxe suivante d' YAML s pour définir la configuration de la trace de pile :

# Use 'tracing' key in a YAML configuration file (required)
# Use 'com.instana.tracing' key in the agent configuration.yaml file (accepted for backward compatibility)
tracing:
  global:
    stack-trace: <string>
    stack-trace-length: <int>
  <technology>:          # Optional: override global settings per technology
    stack-trace: <string>
    stack-trace-length: <int>
Tableau 2. Champs de configuration de la trace de pile
Zone Description Valeurs prises en charge
stack-trace Niveau de trace de pile all (par défaut) : collecter les traces de pile pour tous les segments; error: collecter les traces de pile uniquement pour les segments EXIT présentant des erreurs. Les traces de pile ne sont pas collectées pour les segments ENTRY (par exemple, les segments de requête de type « ASP.NET »), car ils ne contiennent généralement que des trames au niveau du framework qui présentent peu d'intérêt pour le diagnostic; none: Désactiver la collecte des traces de pile. Quel que soit le mode configuré, les segments d’entrée et de sortie de la fonction « HTTP » qui génèrent une erreur (span.ec=1) renvoient toujours une trace de pile.
stack-trace-length Profondeur de la trace de pile 1 – 200 (par défaut : 35). En cas de segments EXIT erronés, le traceur peut ne pas tenir compte de cette limite et capturer la pile dans son intégralité.
Remarque :
La clé <technology> de la section tracing accepte tout identifiant de technologie pris en charge par Tracer de.NET Framework (par exemple, aspnet, sqlserver). Les paramètres propres à chaque technologie ont priorité sur tracing.global.

Ordre de priorité des paramètres de configuration

Les paramètres de configuration de la trace de pile sont appliqués selon l'ordre de priorité suivant :

  1. Configuration de la trace de pile issue du fichier de configuration « YAML », transmise via la variable d'environnement INSTANA_CONFIG_PATH .
  2. Configuration de la trace de pile définie via les variables d'environnement INSTANA_STACK_TRACE et INSTANA_STACK_TRACE_LENGTH.
  3. Configuration de la trace de pile à partir du fichier configuration.yaml de l'agent.

La priorité est évaluée et appliquée séparément pour les paramètres relatifs au niveau de la trace de pile et à la longueur de la trace de pile.