Managed Service for OpenTelemetry:Relatar dados de rastreamento .NET com OpenTelemetry

Pré-requisitos

Contexto

O OpenTelemetry .NET oferece suporte à instrumentação automática e manual.

• Instrumentação automática

  • Versões compatíveis do .NET e .NET Framework:

    • .NET SDK 6+

    • Sem suporte atual para .NET Framework.

  • Para obter a lista de frameworks compatíveis, consulte a documentação oficial do OpenTelemetry.

• Instrumentação manual e semiautomática

  • Versões compatíveis:

    • .NET ≥ 5,0

    • .NET Core ≥ 2,0

    • .NET Framework ≥ 4.6.1

  • Frameworks compatíveis:

    Versões de frameworks compatíveis

    Framework	.NET Framework (Windows)	.NET (multiplataforma, anteriormente .NET Core)	Versões compatíveis	Link
    ASP.NET	Compatível	ASP.NET (.NET Framework) MVC / WebApi não é compatível com .NET.	-	-
    ASP.NET Core	/	Compatível	-	-
    Azure	Compatível	Compatível	Oferece suporte a pacotes com o prefixo Azure. lançados após 1º de outubro de 2021.	Azure SDK
    Elasticsearch	Compatível	Compatível	Elastic.Clients.Elasticsearch: Compatível com versões [8.0.0, 8.10.0). A instrumentação Elastic.Transport oferece suporte às versões 8.10.0 e posteriores.	Elastic.Clients.Elasticsearch
    Elastic.Transport	Compatível	Compatível	≥0.4.16	Elastic.Transport
    Entity Framework Core	/	Compatível	≥6.0.12	Microsoft.EntityFrameworkCore
    GraphQL	/	Compatível	≥7.5.0	GraphQL
    Grpc.Net.Client	Compatível	Compatível	[2.52.0, 3.0.0)	Grpc.Net.Client
    HttpClient	Compatível	Compatível	*	System.Net.Http.HttpClient System.Net.HttpWebRequest
    Quartz	Incompatível com as versões 4.7.1 e anteriores do .NET Framework.	Compatível	≥3.4.0	Quartz
    MassTransit	/	Compatível	≥8.0.0	MassTransit
    MongoDB	Compatível	Compatível	[2.13.3, 3.0.0)	MongoDB.Driver.Core
    MySqlConnector	Compatível	Compatível	≥2.0.0	MySqlConnector
    MySql.Data	/	Compatível	≥8.1.0	MySql.Data
    Npgsql	Compatível	Compatível	≥6.0.0	Npgsql
    NServiceBus	Compatível	Compatível	≥8.0.0	NServiceBus
    SqlClient	Compatível	Compatível	Microsoft.Data.SqlClient v3.* não é compatível.	Microsoft.Data.SqlClient System.Data.SqlClient System.Data (incluído no .NET Framework)
    StackExchange.Redis	/	Compatível	[2.0.405, 3.0.0)	StackExchange.Redis
    WCF Client	Compatível	Compatível	-	-
    WCF Service	Compatível	/	-	-

Exemplo de demonstração

Repositório: dotnet-demo

Método 1: Instrumentação automática

Requisitos de versão

• .NET SDK 6+

• Sem suporte atual para instrumentação automática no .NET Framework.

1. Crie uma aplicação web com ASP.NET Core.

   1. Crie uma aplicação de demonstração.

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

   2. Substitua o conteúdo de Properties/launchSettings.json pela configuração a seguir.

      {
        "$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 a aplicação.

      dotnet build

2. Configure a instrumentação automática para a aplicação.

   1. Baixe e execute o script de instalação da instrumentação automática do 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. Defina as variáveis de ambiente e execute o script de instrumentação automática do OpenTelemetry .NET.

      Substitua <serviceName> pelo nome do seu serviço. Substitua <endpoint> e <token> pelo endpoint e token de autenticação obtidos na seção Pré-requisitos.

      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 obter mais variáveis de ambiente para a instrumentação automática do OpenTelemetry .NET, consulte Variáveis de ambiente da instrumentação automática do OpenTelemetry .NET.

3. Execute e acesse a aplicação.

   1. Execute a aplicação.

      dotnet run

   2. Execute o comando a seguir para acessar a aplicação. Os traces gerados são relatados automaticamente ao Managed Service for OpenTelemetry.

      curl localhost:8080/

Método 2: Instrumentação manual

1. No diretório dotnet-demo/opentelemetry-demo/manual-demo do repositório de código de exemplo, instale as dependências do OpenTelemetry para instrumentação 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. No arquivo OpentelemetryExporterDemo.cs, crie um TracerProvider do OpenTelemetry, adicione um exportador OTLP usando o protocolo HTTP e configure o nome do serviço e o 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 o arquivo Program.cs para chamar OpentelemetryExporterDemo no 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. Execute o seguinte comando no diretório atual.

   dotnet run

Método 3: Instrumentação semiautomática

O OpenTelemetry oferece suporte à instrumentação automática para dezenas de bibliotecas .NET visando coletar dados de rastreamento. Para obter a lista completa de bibliotecas compatíveis, consulte Bibliotecas compatíveis.

1. Acesse o diretório dotnet-demo/opentelemetry-demo/auto-demo no repositório de código de exemplo e crie uma aplicação web ASP.NET Core.

   Substitua <your-project-name> no comando pelo nome da sua aplicação.

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

2. Adicione as dependências necessárias do OpenTelemetry para observar sua aplicação .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. Adicione a dependência de instrumentação automática.

   Adicione a dependência de instrumentação do ASP.NET Core. Ela gera e relata spans automaticamente quando a aplicação recebe uma solicitação HTTP. Para instrumentar outros frameworks automaticamente, consulte Bibliotecas compatíveis e adicione a dependência correspondente.

   dotnet add package OpenTelemetry.Instrumentation.AspNetCore

4. Modifique o código no arquivo <your-project-name>/Program.cs.

   1. Importe os pacotes necessários no início do arquivo source.

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

   2. Adicione a classe DiagnosticsConfig ao final do arquivo source.

      Substitua <your-service-name> e <your-host-name> pelo nome do seu serviço e nome do 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. Adicione o código de inicialização do OpenTelemetry.

      • Exportar dados via HTTP

        Substitua <http_endpoint> no código a seguir pelo endpoint obtido na seção Pré-requisitos.

        // ...
        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 dados via gRPC

        Substitua <grpc_endpoint> e <token> no código a seguir pelo endpoint e token obtidos na seção Pré-requisitos.

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

   Exemplo completo do 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. Execute o projeto no terminal.

   dotnet run

   Saída de exemplo:

   Localize a URL na saída, como 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 em um navegador. Se a página a seguir for exibida, isso confirma que os dados foram relatados ao console do Managed Service for OpenTelemetry.

   Esta é a página de boas-vindas padrão do ASP.NET Core para a aplicação semi_auto_demo. O nome da aplicação semi_auto_demo aparece na barra de navegação superior e a página exibe um título Welcome.

Visualizar dados de monitoramento

Na página Applications do console do Managed Service for OpenTelemetry, clique no nome da aplicação. Na página exibida, visualize os dados de rastreamento.