Instrumentation Zero-code .NET

Utilisez l’instrumentation Zero-code pour .NET pour envoyer des traces et métriques depuis des applications et services .NET vers des solutions d’observabilité sans avoir à modifier leur code source.

Pour apprendre comment instrumenter votre code, lisez Instrumentation manuelle.

Compatibilité

L’instrumentation Zero-code pour .NET devrait fonctionner avec tous les systèmes d’exploitation et versions de .NET officiellement supportés.

La version minimale supportée du .NET Framework est 4.6.2.

Les architectures de processeur supportées sont :

• x86
• AMD64 (x86-64)
• ARM64 (Expérimental)

Les tests d’intégration continue s’exécutent sur les systèmes d’exploitation suivants :

• Alpine x64
• Alpine ARM64
• Debian x64
• Debian ARM64
• CentOS Stream 9 x64
• macOS Ventura 13 x64
• Microsoft Windows Server 2022 x64
• Ubuntu 20.04 LTS x64
• Ubuntu 22.04 LTS ARM64

Configuration

Pour instrumenter automatiquement une application .NET, téléchargez et exécutez le script d’installation pour votre système d’exploitation.

Linux et macOS

Téléchargez et exécutez le script .sh :

# Télécharger le script bash {#download-the-bash-script}
curl -sSfL https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh -O

# Installer les fichiers principaux {#install-core-files} {#install-core-files} {#install-core-files}
sh ./otel-dotnet-auto-install.sh

# Autoriser l'exécution du script d'instrumentation {#enable-execution-for-the-instrumentation-script}
chmod +x $HOME/.otel-dotnet-auto/instrument.sh

# Configurer l'instrumentation pour la session shell actuelle {#setup-the-instrumentation-for-the-current-shell-session}
. $HOME/.otel-dotnet-auto/instrument.sh

# Exécuter votre application avec instrumentation {#run-your-application-with-instrumentation} {#run-your-application-with-instrumentation}
OTEL_SERVICE_NAME=myapp OTEL_RESOURCE_ATTRIBUTES=deployment.environment=staging,service.version=1.0.0 ./MyNetApp

brew install coreutils

Windows (PowerShell)

Sur Windows, utilisez le module PowerShell en tant qu’Administrateur.

# PowerShell 5.1 est requis
#Requires -PSEdition Desktop

# Télécharger le module
$module_url = "https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/OpenTelemetry.DotNet.Auto.psm1"
$download_path = Join-Path $env:temp "OpenTelemetry.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $module_url -OutFile $download_path -UseBasicParsing

# Importer le module pour utiliser ses fonctions
Import-Module $download_path

# Installer les fichiers principaux (méthode en ligne vs hors ligne)
Install-OpenTelemetryCore
Install-OpenTelemetryCore -LocalPath "C:\Path\To\OpenTelemetry.zip"

# Configurer l'instrumentation pour la session PowerShell actuelle
Register-OpenTelemetryForCurrentSession -OTelServiceName "MyServiceDisplayName"

# Exécuter votre application avec instrumentation
.\MyNetApp.exe

# Vous pouvez obtenir des informations d'utilisation en appelant les commandes suivantes

# Lister toutes les commandes disponibles
Get-Command -Module OpenTelemetry.DotNet.Auto

# Obtenir les informations d'utilisation d'une commande
Get-Help Install-OpenTelemetryCore -Detailed

Instrumenter un Service Windows exécutant une application .NET

Utilisez le module PowerShell OpenTelemetry.DotNet.Auto.psm1 pour configurer l’instrumentation automatique pour un Service Windows :

# Importer le module
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# Installer les fichiers principaux
Install-OpenTelemetryCore

# Configurer l'instrumentation de votre Service Windows
Register-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName" -OTelServiceName "MyServiceDisplayName"

Configuration pour Service Windows

Pour les applications .NET Framework, vous pouvez configurer les paramètres OTEL_ les plus courants (comme OTEL_RESOURCE_ATTRIBUTES) via appSettings dans App.config.

L’alternative est de définir des variables d’environnement pour le Service Windows dans le Registre Windows.

La clé de registre d’un Service Windows donné (nommé $svcName) est située sous :

HKLM\SYSTEM\CurrentControlSet\Services\$svcName

Les variables d’environnement sont définies dans un REG_MULTI_SZ (valeur de registre multiligne) appelé Environment dans le format suivant :

Var1=Value1
Var2=Value2

Instrumenter une application ASP.NET déployée sur IIS

Utilisez le module PowerShell OpenTelemetry.DotNet.Auto.psm1 pour configurer l’instrumentation automatique pour IIS :

# Importer le module
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# Installer les fichiers principaux
Install-OpenTelemetryCore

# Configurer l'instrumentation IIS
Register-OpenTelemetryForIIS

Configuration pour les applications ASP.NET

Pour les applications ASP.NET, vous pouvez configurer les paramètres OTEL_ les plus courants (comme OTEL_SERVICE_NAME) via appSettings dans Web.config.

Si un nom de service n’est pas explicitement configuré, un nom sera généré pour vous. Si l’application est hébergée sur IIS dans .NET Framework, cela utilisera SiteName\VirtualDirectoryPath ex : MySite\MyApp

Pour les applications ASP.NET Core, vous pouvez utiliser les éléments <environmentVariable> à l’intérieur du bloc <aspNetCore> de votre fichier Web.config pour définir la configuration via des variables d’environnement.

Configuration avancée

Vous pouvez ajouter les <environmentVariables> dans applicationHost.config pour définir des variables d’environnement pour des pools d’applications donnés.

Envisagez de définir des variables d’environnement communes pour toutes les applications déployées sur IIS en définissant les variables d’environnement pour les Services Windows W3SVC et WAS.

Paquet NuGet

Vous pouvez instrumenter les applications self-contained en utilisant les paquets NuGet. Consulter Paquets NuGet pour plus d’informations.

Instrumenter un conteneur

Pour un exemple d’instrumentation de conteneur Docker, consultez cet exemple sur GitHub.

Vous pouvez également utiliser l' Opérateur OpenTelemetry pour Kubernetes.

Configuration de l’agent

Pour voir la gamme complète d’options de configuration, consultez Configuration et paramètres.

Corrélation log vers trace

Le SDK .NET OpenTelemetry corrèle automatiquement les journaux aux données de trace. Quand les journaux sont émis dans le contexte d’une trace active, les champs TraceId, SpanId, TraceState, qui forment le contexte de la trace, sont automatiquement remplis.

Voici des journaux produits par une application console servant d’exemple :

"logRecords": [
    {
        "timeUnixNano": "1679392614538226700",
        "severityNumber": 9,
        "severityText": "Information",
        "body": {
            "stringValue": "Success! Today is: {Date:MMMM dd, yyyy}"
        },
        "flags": 1,
        "traceId": "21df288eada1ce4ace6c40f39a6d7ce1",
        "spanId": "a80119e5a05fed5a"
    }
]

Pour plus d’informations, consultez :

• SDK .NET OpenTelemetry
• Spécification OpenTelemetry

Bibliothèques et frameworks supportés

L’instrumentation Zero-code pour .NET supporte une grande variété de bibliothèques. Pour une liste complète, voir Instrumentations.

Dépannage

Pour voir la télémétrie de votre application directement sur la sortie standard, ajoutez console à la valeur des variables d’environnement suivantes avant de lancer votre application :

• OTEL_TRACES_EXPORTER
• OTEL_METRICS_EXPORTER
• OTEL_LOGS_EXPORTER

Pour les étapes générales de dépannage et les solutions à des problèmes spécifiques, consultez la page Dépannage.

Étapes suivantes

Après avoir configuré l’instrumentation automatique pour votre application ou votre service, vous pourriez souhaiter envoyer des traces et métriques personnalisées ou ajouter une instrumentation manuelle pour collecter des données de télémétrie personnalisées.

Désinstallation

Linux et macOS { #uninstall-unix }

Sur Linux et macOS, les étapes d’installation n’affectent que la session shell actuelle donc aucune désinstallation explicite n’est requise.

Windows (PowerShell) { #uninstall-windows }

Sur Windows, utilisez le module PowerShell en tant qu’Administrateur.

# PowerShell 5.1 est requis
#Requires -PSEdition Desktop

# Importer le module précédemment installé
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# Si IIS était précédemment enregistré, le désenregistrer
Unregister-OpenTelemetryForIIS

# Si des services Windows étaient précédemment enregistrés, les désenregistrer
Unregister-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName"

# Finalement, désinstaller l'instrumentation OpenTelemetry
Uninstall-OpenTelemetryCore