Instrumenter et exporter les données de trace .NET avec OpenTelemetry - Application Real-Time Monitoring Service

Prérequis

Obtenir un endpoint

Connectez-vous à la console Application Real-Time Monitoring Service (ARMS). Dans le volet de navigation de gauche, cliquez sur Integration Center.
Sur la page Integration Center, cliquez sur la carte OpenTelemetry dans la section Server-side Applications.
Dans le panneau OpenTelemetry, cliquez sur l'onglet Start Integration, puis sélectionnez la région dans laquelle vous souhaitez envoyer les données.

Remarque
Lorsque vous accédez à une région pour la première fois, les ressources y sont automatiquement initialisées.
Configurez les paramètres Connection Type et Export Protocol, puis copiez un endpoint.
- Connection Type : Si votre service est déployé sur Alibaba Cloud et se trouve dans la région que vous avez sélectionnée, nous vous recommandons de définir ce paramètre sur Alibaba Cloud VPC Network. Sinon, définissez-le sur Public Network.
- Export Protocol : Définissez ce paramètre sur HTTP (recommandé) ou gRPC en fonction du protocole pris en charge par le client.

Contexte

OpenTelemetry .NET prend en charge l'instrumentation automatique et l'instrumentation manuelle.

Instrumentation automatique
- Versions .NET et .NET Framework prises en charge :
  - .NET SDK 6+
  - Non pris en charge actuellement pour .NET Framework.
- Pour obtenir la liste des frameworks pris en charge, consultez la documentation officielle OpenTelemetry.

Instrumentation manuelle et semi-automatique

Versions prises en charge :
- .NET ≥ 5,0
- .NET Core ≥ 2,0
- .NET Framework ≥ 4.6.1

Frameworks pris en charge :

Versions de framework prises en charge

Framework	.NET Framework (Windows)	.NET (multiplateforme, anciennement .NET Core)	Versions prises en charge	Lien
ASP.NET	Pris en charge	ASP.NET (.NET Framework) MVC / WebApi n'est pas pris en charge sur .NET.	-	-
ASP.NET Core	/	Pris en charge	-	-
Azure	Pris en charge	Pris en charge	Prend en charge les packages avec le préfixe Azure. publiés après le 1er octobre 2021.	Azure SDK
Elasticsearch	Pris en charge	Pris en charge	Elastic.Clients.Elasticsearch : prend en charge les versions [8.0.0, 8.10.0). L'instrumentation Elastic.Transport prend en charge les versions 8.10.0 et ultérieures.	Elastic.Clients.Elasticsearch
Elastic.Transport	Pris en charge	Pris en charge	≥0.4.16	Elastic.Transport
Entity Framework Core	/	Pris en charge	≥6.0.12	Microsoft.EntityFrameworkCore
GraphQL	/	Pris en charge	≥7.5.0	GraphQL
Grpc.Net.Client	Pris en charge	Pris en charge	[2.52.0, 3.0.0)	Grpc.Net.Client
HttpClient	Pris en charge	Pris en charge	*	System.Net.Http.HttpClient System.Net.HttpWebRequest
Quartz	Non pris en charge sur les versions 4.7.1 et antérieures de .NET Framework.	Pris en charge	≥3.4.0	Quartz
MassTransit	/	Pris en charge	≥8.0.0	MassTransit
MongoDB	Pris en charge	Pris en charge	[2.13.3, 3.0.0)	MongoDB.Driver.Core
MySqlConnector	Pris en charge	Pris en charge	≥2.0.0	MySqlConnector
MySql.Data	/	Pris en charge	≥8.1.0	MySql.Data
Npgsql	Pris en charge	Pris en charge	≥6.0.0	Npgsql
NServiceBus	Pris en charge	Pris en charge	≥8.0.0	NServiceBus
SqlClient	Pris en charge	Pris en charge	Microsoft.Data.SqlClient v3.* n'est pas pris en charge.	Microsoft.Data.SqlClient System.Data.SqlClient System.Data (fourni avec .NET Framework)
StackExchange.Redis	/	Pris en charge	[2.0.405, 3.0.0)	StackExchange.Redis
WCF Client	Pris en charge	Pris en charge	-	-
WCF Service	Pris en charge	/	-	-

Démo d'exemple

Référentiel : dotnet-demo

Méthode 1 : Instrumentation automatique

Exigences de version

.NET SDK 6+
L'instrumentation automatique n'est pas prise en charge actuellement pour .NET Framework.

Créez une application web avec ASP.NET Core.

Créez une application de démonstration.

mkdir dotnet-simple-demo
cd dotnet-simple-demo
dotnet new web

Remplacez le contenu du fichier Properties/launchSettings.json par la configuration suivante.

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:8080",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Générez l'application.
```
dotnet build
```

Configurez l'instrumentation automatique pour l'application.
1. Téléchargez et exécutez le script d'installation de l'instrumentation automatique OpenTelemetry .NET.
```
curl -L -O https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh
./otel-dotnet-auto-install.sh
```
2. Définissez les variables d'environnement et exécutez le script d'instrumentation automatique OpenTelemetry .NET.
  
  Remplacez <serviceName> par le nom de votre service. Remplacez <endpoint> et <token> par l'endpoint et le jeton d'authentification obtenus dans la section Prérequis.
```
export OTEL_TRACES_EXPORTER=otlp \
  OTEL_METRICS_EXPORTER=none \
  OTEL_LOGS_EXPORTER=none \
  OTEL_SERVICE_NAME=<serviceName> \
  OTEL_EXPORTER_OTLP_PROTOCOL=grpc
  OTEL_EXPORTER_OTLP_ENDPOINT=<endpoint> \
  OTEL_EXPORTER_OTLP_HEADERS="Authentication=<token>"
. $HOME/.otel-dotnet-auto/instrument.sh
```
  Remarque
  Pour plus d'informations sur les variables d'environnement supplémentaires pour l'instrumentation automatique OpenTelemetry .NET, consultez les variables d'environnement d'instrumentation automatique OpenTelemetry .NET.
Exécutez et accédez à l'application.
1. Exécutez l'application.
```
dotnet run
```
2. Exécutez la commande suivante pour accéder à l'application. Les traces générées sont automatiquement envoyées à Managed Service for OpenTelemetry.
```
curl localhost:8080/
```

Méthode 2 : Instrumentation manuelle

Dans le répertoire dotnet-demo/opentelemetry-demo/manual-demo du référentiel d'exemples de code, installez les dépendances OpenTelemetry pour l'instrumentation manuelle.

dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
dotnet add package OpenTelemetry.Exporter.Console # Optional, to export data to the console.
dotnet add package OpenTelemetry.Extensions.Hosting

Dans le fichier OpentelemetryExporterDemo.cs, créez un TracerProvider OpenTelemetry, ajoutez un exportateur OTLP utilisant le protocole HTTP et configurez le nom du service et l'endpoint.

using System.Diagnostics;
using OpenTelemetry;
using OpenTelemetry.Trace;
using OpenTelemetry.Resources;
using OpenTelemetry.Exporter;
namespace Demo
{
    internal static class OpentelemetryExporterDemo
    {
        internal static void Run()
        {
            Console.WriteLine("otlp running");
            // Set the service name for your application.
            var serviceName = "otlp-test";
            using var tracerProvider = Sdk.CreateTracerProviderBuilder()
                .AddSource(serviceName)
                .SetResourceBuilder(
                ResourceBuilder.CreateDefault().AddService(serviceName))
                .AddOtlpExporter(opt =>
                                 {
                                     // Replace with the endpoint obtained from the Prerequisites section.
                                     opt.Endpoint = new Uri("<endpoint>");
                                     // Use the HTTP protocol to report data.
                                     opt.Protocol = OtlpExportProtocol.HttpProtobuf;
                                 })
                .AddConsoleExporter() // Optional: Exports data to the console.
                .Build();
            for(int i = 0; i<10; i++)
            {
                var MyActivitySource = new ActivitySource(serviceName);
                using var activity = MyActivitySource.StartActivity("SayHello");
                activity?.SetTag("bar", "Hello World");
            }
        }
    }
}

Modifiez le fichier Program.cs pour appeler OpentelemetryExporterDemo dans la méthode Main.

using System.Diagnostics;
using System.Net.Http;
using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
namespace Demo
{
    public class Otlp
    {
        public static void Main(string[] args)
        {
            OpentelemetryExporterDemo.Run();
        }
    }
}

Exécutez la commande suivante dans le répertoire actuel.
```
dotnet run
```

Méthode 3 : Instrumentation semi-automatique

OpenTelemetry prend en charge l'instrumentation automatique de dizaines de bibliothèques .NET pour collecter les données de trace. Pour obtenir la liste complète des bibliothèques prises en charge, consultez les bibliothèques prises en charge.

Accédez au répertoire dotnet-demo/opentelemetry-demo/auto-demo dans le référentiel d'exemples de code et créez une application web ASP.NET Core.
Remplacez <your-project-name> dans la commande par le nom de votre application.
```
mkdir <your-project-name>
cd <your-project-name>
dotnet new mvc
```

Ajoutez les dépendances OpenTelemetry requises pour observer votre application .NET.

dotnet add package OpenTelemetry.Exporter.Console # Export collected data to the console
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol # Export data using the OTLP protocol

Ajoutez la dépendance d'instrumentation automatique.
Ajoutez la dépendance d'instrumentation ASP.NET Core. Elle génère et exporte automatiquement des spans lorsque l'application reçoit une requête HTTP. Pour instrumenter automatiquement d'autres frameworks, consultez les bibliothèques prises en charge et ajoutez la dépendance correspondante.
```
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
```

Modifiez le code dans le fichier <your-project-name>/Program.cs.

Importez les packages requis au début du fichier source.

using System.Diagnostics;
using OpenTelemetry.Exporter;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

Ajoutez la classe DiagnosticsConfig à la fin du fichier source.

Remplacez <your-service-name> et <your-host-name> par le nom de votre service et le nom de votre hôte.

public static class DiagnosticsConfig
{
    public const string ServiceName = "<your-service-name>";
    public const string HostName = "<your-host-name>";
    public static ActivitySource ActivitySource = new ActivitySource(ServiceName);
}

Ajoutez le code d'initialisation OpenTelemetry.

Exporter les données via HTTP

Remplacez <http_endpoint> dans le code suivant par l'endpoint obtenu dans la section Prérequis.

// ...
builder.Services.AddOpenTelemetry()
    .WithTracing(tracerProviderBuilder =>
        tracerProviderBuilder
            .AddSource(DiagnosticsConfig.ActivitySource.Name)
            .SetResourceBuilder(OpenTelemetry.Resources.ResourceBuilder.CreateDefault()
                .AddAttributes(new Dictionary<string, object> {
                    {"service.name", DiagnosticsConfig.ServiceName},
                    {"host.name",DiagnosticsConfig.HostName}
                }))
            .AddAspNetCoreInstrumentation()
            .AddConsoleExporter() // Optional: Export trace data to the console.
            .AddOtlpExporter(opt =>
            {
                // Export data over HTTP.
                opt.Endpoint = new Uri("<http_endpoint>");
                opt.Protocol = OtlpExportProtocol.HttpProtobuf;
            })
     );
// ...

Exporter les données via gRPC

Remplacez <grpc_endpoint> et <token> dans le code suivant par l'endpoint et le jeton obtenus dans la section Prérequis.

// ...
builder.Services.AddOpenTelemetry()
    .WithTracing(tracerProviderBuilder =>
        tracerProviderBuilder
            .AddSource(DiagnosticsConfig.ActivitySource.Name)
            .SetResourceBuilder(OpenTelemetry.Resources.ResourceBuilder.CreateDefault()
                .AddAttributes(new Dictionary<string, object> {
                    {"service.name", DiagnosticsConfig.ServiceName},
                    {"host.name",DiagnosticsConfig.HostName}
                }))
            .AddAspNetCoreInstrumentation()
            .AddConsoleExporter() // Optional: Export trace data to the console.
            .AddOtlpExporter(opt =>
            {
                // Export data over gRPC.
                opt.Endpoint = new Uri("<grpc_endpoint>");
                opt.Headers = "Authentication=<token>";
                opt.Protocol = OtlpExportProtocol.Grpc;
            })
     );
// ...

Exemple complet de Program.cs

// Import the required packages.
using System.Diagnostics;
using OpenTelemetry.Exporter;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllersWithViews();
// Initialize OpenTelemetry.
builder.Services.AddOpenTelemetry()
    .WithTracing(tracerProviderBuilder =>
        tracerProviderBuilder
            .AddSource(DiagnosticsConfig.ActivitySource.Name)
            .SetResourceBuilder(OpenTelemetry.Resources.ResourceBuilder.CreateDefault()
                .AddAttributes(new Dictionary<string, object> {
                    {"service.name", DiagnosticsConfig.ServiceName},
                    {"host.name",DiagnosticsConfig.HostName}
                }))
            .AddAspNetCoreInstrumentation()
            .AddConsoleExporter() // Optional: Export trace data to the console.
            .AddOtlpExporter(opt =>
            {
                // Export data over HTTP.
                opt.Endpoint = new Uri("<http_endpoint>");
                opt.Protocol = OtlpExportProtocol.HttpProtobuf;
                // To export data over gRPC, uncomment the following lines.
                // opt.Endpoint = new Uri("<grpc_endpoint>");
                // opt.Headers = "Authentication=<token>";
                // opt.Protocol = OtlpExportProtocol.Grpc;
            })
     );
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");
app.Run();
// Create the DiagnosticsConfig class.
public static class DiagnosticsConfig
{
    public const string ServiceName = "<your-service-name>"; // Service name
    public const string HostName = "<your-host-name>"; // Host name
    public static ActivitySource ActivitySource = new ActivitySource(ServiceName);
}

Exécutez le projet depuis votre terminal.

dotnet run

Exemple de sortie :

Recherchez l'URL dans la sortie, telle que http://localhost:5107.

Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5107
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: /path/to/<your-project-name>

Ouvrez http://localhost:5107 dans un navigateur. Si la page suivante s'affiche, cela confirme que les données ont été envoyées à la console Managed Service for OpenTelemetry.

Cette page est la page d'accueil par défaut d'ASP.NET Core pour l'application semi_auto_demo. Le nom de l'application semi_auto_demo apparaît dans la barre de navigation supérieure et la page affiche un titre Welcome.

Consulter les données de surveillance

Connectez-vous à la console ARMS. Dans le volet de navigation de gauche, choisissez Application Monitoring > Applications. Sur la page Applications, cliquez sur le nom de l'application. Sur la page qui s'affiche, consultez les données de trace.

Remarque

Si l'icône s'affiche dans la colonne Language, l'application est connectée à Application Monitoring. Si un trait d'union (-) s'affiche, l'application est connectée à Managed Service for OpenTelemetry.