Configuration et paramètres

Méthodes de configuration

Vous pouvez appliquer ou modifier les paramètres de configuration de la manière suivante, les variables d’environnement ayant la priorité sur le fichier App.config ou Web.config :

1. Variables d’environnement

   Les variables d’environnement sont le moyen principal de configurer les paramètres.

2. Fichier App.config ou Web.config

   Pour une application s’exécutant sur .NET Framework, vous pouvez utiliser un fichier de configuration web (web.config) ou un fichier de configuration d’application (app.config) pour configurer les paramètres OTEL_*.

   ⚠️ Seuls les paramètres commençant par OTEL_ peuvent être définis en utilisant App.config ou Web.config. Cependant, les paramètres suivants ne sont pas supportés :

   • OTEL_DOTNET_AUTO_HOME
   • OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES
   • OTEL_DOTNET_AUTO_FAIL_FAST_ENABLED
   • OTEL_DOTNET_AUTO_[TRACES|METRICS|LOGS]_INSTRUMENTATIONS_ENABLED
   • OTEL_DOTNET_AUTO_[TRACES|METRICS|LOGS]_{INSTRUMENTATION_ID}_INSTRUMENTATION_ENABLED
   • OTEL_DOTNET_AUTO_LOG_DIRECTORY
   • OTEL_LOG_LEVEL
   • OTEL_DOTNET_AUTO_NETFX_REDIRECT_ENABLED

   Exemple avec le paramètre OTEL_SERVICE_NAME :

   <configuration>
   <appSettings>
       <add key="OTEL_SERVICE_NAME" value="my-service-name" />
   </appSettings>
   </configuration>
   

3. Détection automatique du nom de service

   Si aucun nom de service n’est explicitement configuré, il sera généré pour vous. Cela peut être utile dans certaines circonstances.

   • Si l’application est hébergée sur IIS dans .NET Framework, ce sera SiteName\VirtualPath ex : MySite\MyApp
   • Si ce n’est pas le cas, le nom de l' Assembly d’entrée de l’application sera utilisé.

Par défaut, nous recommandons d’utiliser les variables d’environnement pour la configuration. Cependant, si un paramètre donné le supporte, alors :

• utilisez Web.config pour configurer une application ASP.NET (.NET Framework),
• utilisez App.config pour configurer un Service Windows (.NET Framework).

Paramètres globaux

[1] Si OTEL_DOTNET_AUTO_FAIL_FAST_ENABLED est défini à true alors les processus exclus de l’instrumentation par OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES échoueront au lieu de continuer silencieusement.

[2] Notez que les applications lancées via dotnet MyApp.dll ont le nom de processus dotnet ou dotnet.exe.

Ressources

Une ressource est la représentation immuable de l’entité produisant la télémétrie. Voir Conventions sémantiques des ressources pour plus de détails.

Attributs de ressource

Détecteurs de ressource

Les détecteurs de ressource suivants sont inclus et activés par défaut :

Propagateurs

Les propagateurs permettent aux applications de partager le contexte. Voir la spécification OpenTelemetry pour plus de détails.

Échantillonneurs

Les échantillonneurs vous permettent de contrôler le bruit potentiel et la surcharge introduits par l’instrumentation OpenTelemetry en sélectionnant quelles traces vous voulez collecter et exporter. Voir la spécification OpenTelemetry pour plus de détails.

[1] : Les valeurs supportées sont :

• always_on,
• always_off,
• traceidratio,
• parentbased_always_on,
• parentbased_always_off,
• parentbased_traceidratio.

[2] : Pour les échantillonneurs traceidratio et parentbased_traceidratio : Probabilité d’échantillonnage, un nombre dans la plage [0..1], ex. “0.25”. La valeur par défaut est 1.0.

Exportateurs

Les exportateurs transmettent la télémétrie.

Exportateur de traces

Exportateur de métriques

Exportateur de logs

OTLP

Statut : Stable

Pour activer l’exportateur OTLP, définissez la variable d’environnement OTEL_TRACES_EXPORTER/OTEL_METRICS_EXPORTER/OTEL_LOGS_EXPORTER à otlp.

Pour personnaliser l’exportateur OTLP en utilisant des variables d’environnement, voir la documentation de l’exportateur OTLP. Les variables d’environnement importantes incluent :

[1] : Considérations sur le OTEL_EXPORTER_OTLP_PROTOCOL :

• L’Instrumentation Automatique .NET OpenTelemetry utilise par défaut http/protobuf, ce qui diffère de la valeur par défaut du SDK .NET OpenTelemetry qui est grpc.
• Sur .NET 6 et supérieur, l’application doit référencer Grpc.Net.Client pour utiliser le protocole d’exportateur OTLP grpc. Par exemple, en ajoutant <PackageReference Include="Grpc.Net.Client" Version="2.65.0" /> au fichier .csproj.
• Sur .NET Framework, le protocole d’exportateur OTLP grpc n’est pas supporté.

[2] : Les valeurs reconnues (insensibles à la casse) pour OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE sont :

• Cumulative : Choisir la temporalité d’agrégation cumulative pour tous les types d’instruments.
• Delta : Choisir la temporalité d’agrégation Delta pour les types d’instruments Counter, Asynchronous Counter et Histogram, choisir l’agrégation Cumulative pour les types d’instruments UpDownCounter et Asynchronous UpDownCounter.
• LowMemory : Cette configuration utilise la temporalité d’agrégation Delta pour Synchronous Counter et Histogram et utilise la temporalité d’agrégation Cumulative pour les types d’instruments Synchronous UpDownCounter, Asynchronous Counter, et Asynchronous UpDownCounter.
  • ⚠️ Cette valeur connue de la spécification n’est pas supportée.

Prometheus

Statut : Expérimental

Pour activer l’exportateur Prometheus, définissez la variable d’environnement OTEL_METRICS_EXPORTER à prometheus.

L’exportateur expose le point de terminaison HTTP des métriques sur http://localhost:9464/metrics et il met en cache les réponses pendant 300 millisecondes.

Voir la documentation Prometheus Exporter HttpListener. pour en savoir plus.

Zipkin

Statut : Stable

Pour activer l’exportateur Zipkin, définissez la variable d’environnement OTEL_TRACES_EXPORTER à zipkin.

Pour personnaliser l’exportateur Zipkin en utilisant des variables d’environnement, voir la documentation de l’exportateur Zipkin. Les variables d’environnement importantes incluent :

Paramètres supplémentaires

RuleEngine

RuleEngine est une fonctionnalité qui valide les assemblies API, SDK, Instrumentation, et Exporter OpenTelemetry pour des scénarios non supportés, s’assurant que l’instrumentation automatique OpenTelemetry est plus stable en se retirant au lieu de planter. Elle fonctionne sur .NET 6 et supérieur.

Activez RuleEngine seulement pendant la première exécution de l’application, ou quand le déploiement change ou que la bibliothèque d’Instrumentation Automatique est mise à niveau. Une fois validé, il n’y a pas besoin de revalider les règles quand l’application redémarre.

Profileur .NET CLR

Le CLR utilise les variables d’environnement suivantes pour configurer le profileur. Voir .NET Runtime Profiler Loading pour plus d’informations.

Définir l’Instrumentation Automatique .NET OpenTelemetry comme Profileur .NET CLR est requis pour .NET Framework.

Sur .NET, le Profileur .NET CLR est utilisé seulement pour l’instrumentation bytecode. Si avoir seulement l’instrumentation source est acceptable, vous pouvez désactiver ou supprimer les variables d’environnement suivantes :

COR_ENABLE_PROFILING
COR_PROFILER
COR_PROFILER_PATH_32
COR_PROFILER_PATH_64
CORECLR_ENABLE_PROFILING
CORECLR_PROFILER
CORECLR_PROFILER_PATH
CORECLR_PROFILER_PATH_32
CORECLR_PROFILER_PATH_64

Runtime .NET

Sur .NET, il est requis de définir la variable d’environnement DOTNET_STARTUP_HOOKS.

Les variables d’environnement DOTNET_ADDITIONAL_DEPS et DOTNET_SHARED_STORE sont utilisées pour atténuer les conflits de version d’assembly dans .NET.

Logs internes

Les chemins de répertoire par défaut pour les journaux internes sont :

• Windows : %ProgramData%\OpenTelemetry .NET AutoInstrumentation\logs
• Linux : /var/log/opentelemetry/dotnet
• macOS : /var/log/opentelemetry/dotnet

Si les répertoires de journaux par défaut ne peuvent pas être créés, l’instrumentation utilise le chemin du dossier temporaire de l’utilisateur actuel à la place.