Instrumentar e relatar dados de rastreamento .NET com OpenTelemetry - Application Real-Time Monitoring Service: Central de Documentação do Alibaba Cloud

Pré-requisitos

Obter um endpoint

Faça logon no console do Application Real-Time Monitoring Service (ARMS). No painel de navegação à esquerda, clique em Integration Center.
Na página Integration Center, clique no cartão OpenTelemetry na seção Server-side Applications.
No painel OpenTelemetry, clique na aba Start Integration e selecione a região para relatório de dados.

Nota
Os recursos são inicializados automaticamente ao acessar uma região pela primeira vez.
Configure os parâmetros Connection Type e Export Protocol e copie um endpoint.
- Connection Type: Se o service estiver implantado na Alibaba Cloud e residir na região selecionada, defina este parâmetro como Alibaba Cloud VPC Network. Caso contrário, defina como Public Network.
- Export Protocol: Defina este parâmetro como HTTP (recomendado) ou gRPC conforme o protocolo compatível com o cliente.

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 uma 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: Oferece suporte às 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.

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

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

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

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"
      }
    }
  }
}

Compile a aplicação.
```
dotnet build
```

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 service. 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.
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 rastros gerados são relatados automaticamente para o Managed Service for OpenTelemetry.
```
curl localhost:8080/
```

Método 2: Instrumentação manual

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

No arquivo OpentelemetryExporterDemo.cs, crie um TracerProvider do OpenTelemetry, adicione um exportador OTLP usando o protocolo HTTP e configure o nome do service 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");
            }
        }
    }
}

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

Execute o comando a seguir 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.

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 aplicação.
```
mkdir <your-project-name>
cd <your-project-name>
dotnet new mvc
```

Adicione as dependências necessárias do OpenTelemetry para observar a 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

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
```

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

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

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

Adicione a classe DiagnosticsConfig ao final do arquivo de source.

Substitua <your-service-name> e <your-host-name> pelo nome do service 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);
}

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

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>

Abra http://localhost:5107 em um navegador. A exibição da página a seguir 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 o título Welcome.

Visualizar dados de monitoramento

Faça logon no console do ARMS. No painel de navegação à esquerda, escolha Application Monitoring > Applications. Na página Applications, clique em no nome da aplicação. Na página exibida, visualize os dados de rastreamento.

Nota

Se o ícone aparecer na coluna Language, a aplicação estará conectada ao Application Monitoring. Se um hífen (-) aparecer, a aplicação estará conectada ao Managed Service for OpenTelemetry.