Application Real-Time Monitoring Service:Reporte de datos de traza .NET con OpenTelemetry

Requisitos previos

Contexto

OpenTelemetry .NET admite la instrumentación automática y manual.

• Instrumentación automática

  • Versiones compatibles de .NET y .NET Framework:

    • .NET SDK 6+

    • Actualmente no es compatible con .NET Framework.

  • Para consultar la lista de frameworks compatibles, revise la documentación oficial de OpenTelemetry.

• Instrumentación manual y semiautomática

  • Versiones compatibles:

    • .NET ≥ 5.0

    • .NET Core ≥ 2.0

    • .NET Framework ≥ 4.6.1

  • Frameworks compatibles:

    Versiones de frameworks compatibles

    Framework	.NET Framework (Windows)	.NET (multiplataforma, anteriormente .NET Core)	Versiones compatibles	Enlace
    ASP.NET	Compatible	ASP.NET (.NET Framework) MVC / WebApi no es compatible con .NET.	-	-
    ASP.NET Core	/	Compatible	-	-
    Azure	Compatible	Compatible	Admite paquetes con el prefijo Azure. publicados después del 1 de octubre de 2021.	Azure SDK
    Elasticsearch	Compatible	Compatible	Elastic.Clients.Elasticsearch: Admite versiones [8.0.0, 8.10.0). La instrumentación Elastic.Transport admite la versión 8.10.0 y posteriores.	Elastic.Clients.Elasticsearch
    Elastic.Transport	Compatible	Compatible	≥0.4.16	Elastic.Transport
    Entity Framework Core	/	Compatible	≥6.0.12	Microsoft.EntityFrameworkCore
    GraphQL	/	Compatible	≥7.5.0	GraphQL
    Grpc.Net.Client	Compatible	Compatible	[2.52.0, 3.0.0)	Grpc.Net.Client
    HttpClient	Compatible	Compatible	*	System.Net.Http.HttpClient System.Net.HttpWebRequest
    Quartz	No es compatible con versiones de .NET Framework 4.7.1 y anteriores.	Compatible	≥3.4.0	Quartz
    MassTransit	/	Compatible	≥8.0.0	MassTransit
    MongoDB	Compatible	Compatible	[2.13.3, 3.0.0)	MongoDB.Driver.Core
    MySqlConnector	Compatible	Compatible	≥2.0.0	MySqlConnector
    MySql.Data	/	Compatible	≥8.1.0	MySql.Data
    Npgsql	Compatible	Compatible	≥6.0.0	Npgsql
    NServiceBus	Compatible	Compatible	≥8.0.0	NServiceBus
    SqlClient	Compatible	Compatible	Microsoft.Data.SqlClient v3.* no es compatible.	Microsoft.Data.SqlClient System.Data.SqlClient System.Data (incluido con .NET Framework)
    StackExchange.Redis	/	Compatible	[2.0.405, 3.0.0)	StackExchange.Redis
    WCF Client	Compatible	Compatible	-	-
    WCF Service	Compatible	/	-	-

Demostración de ejemplo

Repositorio: dotnet-demo

Método 1: Instrumentación automática

Requisitos de versión

• .NET SDK 6+

• Actualmente no se admite la instrumentación automática para .NET Framework.

1. Cree una aplicación web con ASP.NET Core.

   1. Cree una aplicación de demostración.

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

   2. Reemplace el contenido de Properties/launchSettings.json con la siguiente configuración.

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

   3. Compile la aplicación.

      dotnet build

2. Configure la instrumentación automática para la aplicación.

   1. Descargue y ejecute el script de instalación de instrumentación automática de 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. Establezca las variables de entorno y ejecute el script de instrumentación automática de OpenTelemetry .NET.

      Reemplace <serviceName> con el nombre de su servicio. Sustituya <endpoint> y <token> por el endpoint y el token de autenticación obtenidos en la sección Requisitos previos.

      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

      Nota

      Para consultar variables de entorno adicionales para la instrumentación automática de OpenTelemetry .NET, revise Variables de entorno de instrumentación automática de OpenTelemetry .NET.

3. Ejecute y acceda a la aplicación.

   1. Ejecute la aplicación.

      dotnet run

   2. Ejecute el siguiente comando para acceder a la aplicación. Las trazas generadas se reportan automáticamente a Managed Service for OpenTelemetry.

      curl localhost:8080/

Método 2: Instrumentación manual

1. En el directorio dotnet-demo/opentelemetry-demo/manual-demo del repositorio de código de ejemplo, instale las dependencias de OpenTelemetry para la instrumentación manual.

   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

2. En el archivo OpentelemetryExporterDemo.cs, cree un TracerProvider de OpenTelemetry, agregue un exportador OTLP mediante el protocolo HTTP y configure el nombre del servicio y el 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");
               }
           }
       }
   }

3. Modifique el archivo Program.cs para invocar OpentelemetryExporterDemo en el método 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();
           }
       }
   }

4. Ejecute el siguiente comando en el directorio actual.

   dotnet run

Método 3: Instrumentación semiautomática

OpenTelemetry admite la instrumentación automática para decenas de bibliotecas de .NET con el fin de recopilar datos de rastreo. Para consultar la lista completa de bibliotecas compatibles, consulte Supported Libraries.

1. Vaya al directorio dotnet-demo/opentelemetry-demo/auto-demo en el repositorio de código de ejemplo y cree una aplicación web ASP.NET Core.

   Reemplace <your-project-name> en el comando por el nombre de su aplicación.

   mkdir <your-project-name>
   cd <your-project-name>
   dotnet new mvc

2. Agregue las dependencias necesarias de OpenTelemetry para observar su aplicación .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

3. Agregue la dependencia de instrumentación automática.

   Agregue la dependencia de instrumentación de ASP.NET Core. Esta genera y reporta spans automáticamente cuando la aplicación recibe una solicitud HTTP. Para instrumentar otros frameworks de forma automática, consulte Supported Libraries y agregue la dependencia correspondiente.

   dotnet add package OpenTelemetry.Instrumentation.AspNetCore

4. Modifique el código en el archivo <your-project-name>/Program.cs.

   1. Importe los paquetes necesarios al inicio del archivo de código fuente.

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

   2. Agregue la clase DiagnosticsConfig al final del archivo de código fuente.

      Reemplace <your-service-name> y <your-host-name> por el nombre de su servicio y el nombre de su host.

      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);
      }

   3. Agregue el código de inicialización de OpenTelemetry.

      • Exportar datos mediante HTTP

        Reemplace <http_endpoint> en el siguiente código por el endpoint de la sección de requisitos previos.

        // ...
        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;
                    })
             );
        // ...

      • Exportar datos mediante gRPC

        Reemplace <grpc_endpoint> y <token> en el siguiente código por el endpoint y el token de la sección de requisitos previos.

        // ...
        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;
                    })
             );
        // ...

   Ejemplo completo 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);
   }
                               

5. Ejecute el proyecto desde su terminal.

   dotnet run

   Salida de ejemplo:

   Busque la URL en la salida, por ejemplo 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>

6. Abra http://localhost:5107 en un navegador. Si se muestra la siguiente página, se confirma que los datos se han reportado a la consola de Managed Service for OpenTelemetry.

   Esta página es la página de bienvenida predeterminada de ASP.NET Core para la aplicación semi_auto_demo. El nombre de la aplicación semi_auto_demo aparece en la barra de navegación superior y la página muestra un título Welcome.

Consultar datos de monitoreo