Managed Service for OpenTelemetry:Laporkan data jejak .NET dengan OpenTelemetry

Latar Belakang

OpenTelemetry .NET mendukung instrumen otomatis dan instrumen manual.

• Instrumen otomatis

  • Versi .NET dan .NET Framework yang didukung:

    • .NET SDK 6+

    • Saat ini belum didukung untuk .NET Framework.

  • Untuk daftar framework yang didukung, lihat dokumentasi resmi OpenTelemetry.

• Instrumen manual dan semi-otomatis

  • Versi yang didukung:

    • .NET ≥ 5.0

    • .NET Core ≥ 2.0

    • .NET Framework ≥ 4.6.1

  • Framework yang didukung:

    Versi framework yang didukung

    Framework	.NET Framework (Windows)	.NET (cross-platform, sebelumnya .NET Core)	Versi yang didukung	Tautan
    ASP.NET	Didukung	ASP.NET (.NET Framework) MVC / WebApi tidak didukung di .NET.	-	-
    ASP.NET Core	/	Didukung	-	-
    Azure	Didukung	Didukung	Mendukung paket dengan awalan Azure. yang dirilis setelah 1 Oktober 2021.	Azure SDK
    Elasticsearch	Didukung	Didukung	Elastic.Clients.Elasticsearch: Mendukung versi [8.0.0, 8.10.0). Instrumen Elastic.Transport mendukung versi 8.10.0 dan seterusnya.	Elastic.Clients.Elasticsearch
    Elastic.Transport	Didukung	Didukung	≥0.4.16	Elastic.Transport
    Entity Framework Core	/	Didukung	≥6.0.12	Microsoft.EntityFrameworkCore
    GraphQL	/	Didukung	≥7.5.0	GraphQL
    Grpc.Net.Client	Didukung	Didukung	[2.52.0, 3.0.0)	Grpc.Net.Client
    HttpClient	Didukung	Didukung	*	System.Net.Http.HttpClient System.Net.HttpWebRequest
    Quartz	Tidak didukung pada versi .NET Framework 4.7.1 dan sebelumnya.	Didukung	≥3.4.0	Quartz
    MassTransit	/	Didukung	≥8.0.0	MassTransit
    MongoDB	Didukung	Didukung	[2.13.3, 3.0.0)	MongoDB.Driver.Core
    MySqlConnector	Didukung	Didukung	≥2.0.0	MySqlConnector
    MySql.Data	/	Didukung	≥8.1.0	MySql.Data
    Npgsql	Didukung	Didukung	≥6.0.0	Npgsql
    NServiceBus	Didukung	Didukung	≥8.0.0	NServiceBus
    SqlClient	Didukung	Didukung	Microsoft.Data.SqlClient v3.* tidak didukung.	Microsoft.Data.SqlClient System.Data.SqlClient System.Data (disertakan dengan .NET Framework)
    StackExchange.Redis	/	Didukung	[2.0.405, 3.0.0)	StackExchange.Redis
    WCF Client	Didukung	Didukung	-	-
    WCF Service	Didukung	/	-	-

Demo contoh

Repositori: dotnet-demo

Metode 1: Instrumentasi Otomatis

Persyaratan versi

• .NET SDK 6+

• Instrumen otomatis saat ini belum didukung untuk .NET Framework.

1. Buat aplikasi web dengan ASP.NET Core.

   1. Buat aplikasi demo.

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

   2. Ganti konten Properties/launchSettings.json dengan konfigurasi berikut.

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

   3. Buat aplikasi.

      dotnet build

2. Konfigurasikan instrumentasi otomatis untuk aplikasi.

   1. Unduh dan jalankan skrip instalasi instrumen otomatis 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. Atur variabel lingkungan dan jalankan skrip instrumen otomatis OpenTelemetry .NET.

      Ganti <serviceName> dengan nama layanan Anda. Ganti <endpoint> dan <token> dengan titik akhir dan token otentikasi dari bagian Prasyarat.

      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

      Catatan

      Untuk variabel lingkungan tambahan untuk instrumen otomatis OpenTelemetry .NET, lihat Variabel lingkungan instrumen otomatis OpenTelemetry .NET.

3. Jalankan dan akses aplikasi.

   1. Jalankan aplikasi.

      dotnet run

   2. Jalankan perintah berikut untuk mengakses aplikasi. Jejak yang dihasilkan dilaporkan secara otomatis ke Managed Service for OpenTelemetry.

      curl localhost:8080/

Metode 2: Instrumentasi manual

1. Di direktori dotnet-demo/opentelemetry-demo/manual-demo repositori kode contoh, instal dependensi OpenTelemetry untuk instrumen manual.

   dotnet add package OpenTelemetry
   dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
   dotnet add package OpenTelemetry.Exporter.Console # Opsional, untuk mengekspor data ke konsol.
   dotnet add package OpenTelemetry.Extensions.Hosting

2. Di file OpentelemetryExporterDemo.cs, buat OpenTelemetry TracerProvider, tambahkan eksporter OTLP menggunakan protokol HTTP, dan konfigurasikan nama layanan dan titik akhir.

   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");
               // Tetapkan nama layanan untuk aplikasi Anda.
               var serviceName = "otlp-test";
               using var tracerProvider = Sdk.CreateTracerProviderBuilder()
                   .AddSource(serviceName)
                   .SetResourceBuilder(
                   ResourceBuilder.CreateDefault().AddService(serviceName))
                   .AddOtlpExporter(opt =>
                                    {
                                        // Ganti dengan titik akhir yang diperoleh dari bagian Prasyarat.
                                        opt.Endpoint = new Uri("<endpoint>");
                                        // Gunakan protokol HTTP untuk melaporkan data.
                                        opt.Protocol = OtlpExportProtocol.HttpProtobuf;
                                    })
                   .AddConsoleExporter() // Opsional: Mengekspor data ke konsol.
                   .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. Ubah file Program.cs untuk memanggil OpentelemetryExporterDemo di metode 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. Jalankan perintah berikut di direktori saat ini.

   dotnet run

Metode 3: Instrumen semi-otomatis

OpenTelemetry mendukung instrumen otomatis untuk puluhan library .NET guna mengumpulkan data jejak. Untuk daftar lengkap library yang didukung, lihat Library yang Didukung.

1. Buka direktori dotnet-demo/opentelemetry-demo/auto-demo di repositori kode contoh dan buat aplikasi web ASP.NET Core.

   Ganti <your-project-name> dalam perintah dengan nama aplikasi Anda.

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

2. Tambahkan dependensi OpenTelemetry yang diperlukan untuk mengamati aplikasi .NET Anda.

   dotnet add package OpenTelemetry.Exporter.Console # Ekspor data yang dikumpulkan ke konsol
   dotnet add package OpenTelemetry.Extensions.Hosting
   dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol # Ekspor data menggunakan protokol OTLP

3. Tambahkan dependensi instrumen otomatis.

   Tambahkan dependensi instrumen ASP.NET Core. Ini secara otomatis menghasilkan dan melaporkan rentang saat aplikasi menerima permintaan HTTP. Untuk menginstrumen framework lain secara otomatis, lihat Library yang Didukung dan tambahkan dependensi yang sesuai.

   dotnet add package OpenTelemetry.Instrumentation.AspNetCore

4. Ubah kode di file <your-project-name>/Program.cs.

   1. Impor paket yang diperlukan di awal file sumber.

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

   2. Tambahkan kelas DiagnosticsConfig di akhir file sumber.

      Ganti <your-service-name> dan <your-host-name> dengan nama layanan dan nama host Anda.

      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. Tambahkan kode inisialisasi OpenTelemetry.

      • Ekspor data melalui HTTP

        Ganti <http_endpoint> dalam kode berikut dengan titik akhir dari bagian Prasyarat.

        // ...
        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() // Opsional: Ekspor data jejak ke konsol.
                    .AddOtlpExporter(opt =>
                    {
                        // Ekspor data melalui HTTP.
                        opt.Endpoint = new Uri("<http_endpoint>");
                        opt.Protocol = OtlpExportProtocol.HttpProtobuf;
                    })
             );
        // ...

      • Ekspor data melalui gRPC

        Ganti <grpc_endpoint> dan <token> dalam kode berikut dengan titik akhir dan token dari bagian Prasyarat.

        // ...
        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() // Opsional: Ekspor data jejak ke konsol.
                    .AddOtlpExporter(opt =>
                    {
                        // Ekspor data melalui gRPC.
                        opt.Endpoint = new Uri("<grpc_endpoint>");
                        opt.Headers = "Authentication=<token>";
                        opt.Protocol = OtlpExportProtocol.Grpc;
                    })
             );
        // ...

   Contoh Program.cs lengkap

   // Impor paket yang diperlukan.
   using System.Diagnostics;
   using OpenTelemetry.Exporter;
   using OpenTelemetry.Resources;
   using OpenTelemetry.Trace;
   var builder = WebApplication.CreateBuilder(args);
   builder.Services.AddControllersWithViews();
   // Inisialisasi 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() // Opsional: Ekspor data jejak ke konsol.
               .AddOtlpExporter(opt =>
               {
                   // Ekspor data melalui HTTP.
                   opt.Endpoint = new Uri("<http_endpoint>");
                   opt.Protocol = OtlpExportProtocol.HttpProtobuf;
                   // Untuk mengekspor data melalui gRPC, hapus komentar baris berikut.
                   // 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();
   // Buat kelas DiagnosticsConfig.
   public static class DiagnosticsConfig
   {
       public const string ServiceName = "<your-service-name>"; // Nama layanan
       public const string HostName = "<your-host-name>"; // Nama host
       public static ActivitySource ActivitySource = new ActivitySource(ServiceName);
   }
                               

5. Jalankan proyek dari terminal Anda.

   dotnet run

   Contoh output:

   Temukan URL di output, seperti 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. Buka http://localhost:5107 di browser. Jika halaman berikut ditampilkan, berarti data telah berhasil dilaporkan ke konsol Managed Service for OpenTelemetry.

   Halaman ini adalah halaman selamat datang ASP.NET Core default untuk aplikasi semi_auto_demo. Nama aplikasi semi_auto_demo muncul di bilah navigasi atas, dan halaman menampilkan judul Welcome.

Lihat data pemantauan

Di halaman Applications Konsol Managed Service for OpenTelemetry, klik nama aplikasi. Di halaman yang muncul, lihat data jejak.