Application Real-Time Monitoring Service：Gunakan OpenTelemetry untuk melaporkan data jejak aplikasi .NET

Informasi Latar Belakang

OpenTelemetry mendukung instrumentasi otomatis dan manual untuk aplikasi .NET.

• Instrumentasi Otomatis

  • OpenTelemetry mendukung instrumentasi otomatis dengan versi .NET berikut:

    • .NET SDK 6+

    • OpenTelemetry tidak mendukung instrumentasi otomatis dengan .NET Framework.

  • Untuk informasi lebih lanjut tentang kerangka kerja yang didukung oleh OpenTelemetry untuk instrumentasi otomatis, lihat Instrumen yang Tersedia dalam dokumentasi resmi OpenTelemetry.

• Instrumentasi Manual dan Semi-Otomatis

  • Versi yang Didukung

    • .NET 5.0 dan yang lebih baru

    • .NET Core 2.0 dan yang lebih baru

    • .NET Framework 4.6.1 dan yang lebih baru

  • Kerangka Kerja yang Didukung

    Kerangka Kerja dan Versi yang Didukung

    Kerangka Kerja	Didukung pada .NET Framework hanya untuk Windows	Didukung pada .NET lintas platform (.NET Core)	Versi yang Didukung	Pustaka yang Diinstrumen
    ASPNET	Ya	ASP.NET (.NET Framework) MVC dan ASP.NET Web API tidak didukung.	Tidak Berlaku	Tidak Berlaku
    ASPNETCORE	Tidak Berlaku	Ya	Tidak Berlaku	Tidak Berlaku
    Azure	Ya	Ya	Paket dengan awalan Azure. yang dirilis setelah 1 Oktober 2021 didukung.	Azure SDK
    Elasticsearch	Ya	Ya	Klien Elasticsearch .NET dari V8.0.0 hingga, tetapi tidak termasuk, V8.10.0 didukung. V8.10.0 dan yang lebih baru didukung oleh kerangka kerja Elasticsearch Transport.	Elastic.Clients.Elasticsearch
    Elasticsearch Transport	Ya	Ya	V0.4.16 dan yang lebih baru	Elastic.Transport
    Entity Framework Core	Tidak Berlaku	Ya	V6.0.12 dan yang lebih baru	Microsoft.EntityFrameworkCore
    GraphQL	Tidak Berlaku	Ya	V7.5.0 dan yang lebih baru	GraphQL
    gRPC Client	Ya	Ya	V2.52.0 hingga, tetapi tidak termasuk, V3.0.0	Grpc.Net.Client
    HttpClient	Ya	Ya	*	System.Net.Http.HttpClient System.Net.HttpWebRequest
    Quartz	V4.7.1 dan yang lebih lama tidak didukung.	Ya	V3.4.0 dan yang lebih baru	Quartz
    MassTransit	Tidak Berlaku	Ya	V8.0.0 dan yang lebih baru	MassTransit
    MongoDB	Ya	Ya	V2.13.3 hingga, tetapi tidak termasuk, V3.0.0	MongoDB.Driver.Core
    MySQL Connector	Ya	Ya	V2.0.0 dan yang lebih baru	MySqlConnector
    MySQL Data	Tidak Berlaku	Ya	V8.1.0 dan yang lebih baru	MySql.Data
    Npgsql	Ya	Ya	V6.0.0 dan yang lebih baru	Npgsql
    NServiceBus	Ya	Ya	V8.0.0 dan yang lebih baru	NServiceBus
    SQL Client	Ya	Ya	Microsoft.Data.SqlClient V3 tidak didukung.	Microsoft.Data.SqlClient System.Data.SqlClient System.Data (dikirim bersama dengan .NET Framework)
    StackExchange.Redis	Tidak Berlaku	Ya	V2.0.405 hingga, tetapi tidak termasuk, V3.0.0	StackExchange.Redis
    WCF Client	Ya	Ya	Tidak Berlaku	Tidak Berlaku
    WCF Service	Ya	Tidak Berlaku	Tidak Berlaku	Tidak Berlaku

Kode Contoh

Unduh kode contoh dari dotnet-demo.

Metode 1: Konfigurasikan instrumentasi otomatis untuk aplikasi

Batasan

• OpenTelemetry hanya mendukung instrumentasi otomatis menggunakan OpenTelemetry SDK untuk .NET 6.0 atau yang lebih baru.

• OpenTelemetry tidak mendukung instrumentasi otomatis menggunakan .NET Framework.

1. Gunakan ASP.NET Core untuk membuat aplikasi web.

   1. Buat aplikasi menggunakan kode contoh.

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

   2. Tambahkan kode berikut ke file Properties/launchSettings.json:

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

   3. Bangun aplikasi.

      dotnet build

2. Konfigurasikan instrumentasi otomatis untuk aplikasi.

   1. Unduh dan jalankan skrip instalasi untuk instrumentasi otomatis menggunakan OpenTelemetry SDK untuk .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. Konfigurasikan variabel lingkungan dan jalankan skrip instrumentasi otomatis.

      Ganti <serviceName> dengan nama aplikasi Anda. Ganti <endpoint> dan <token> dengan titik akhir dan token yang diperoleh di bagian Prasyarat dari topik ini.

      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 informasi lebih lanjut tentang cara mengonfigurasi variabel lingkungan untuk instrumentasi otomatis menggunakan OpenTelemetry SDK untuk .NET, lihat Konfigurasi dan Pengaturan dalam dokumentasi resmi OpenTelemetry.

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 pada aplikasi

1. Pergi ke direktori dotnet-demo/opentelemetry-demo/manual-demo dan tambahkan dependensi OpenTelemetry berikut yang diperlukan untuk menginstrumentasi aplikasi secara manual:

   dotnet add package OpenTelemetry
   dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
   dotnet add package OpenTelemetry.Exporter.Console # Opsional. Dependensi ini diperlukan jika Anda ingin mengekspor data di konsol.
   dotnet add package OpenTelemetry.Extensions.Hosting

2. Di file OpentelemetryExporterDemo.cs, buat OpenTelemetry TracerProvider, tambahkan OtlpExporter berbasis HTTP, lalu tentukan nama aplikasi yang datanya jejak dilaporkan dan titik akhir yang digunakan untuk melaporkan data jejak.

   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");
               // Tentukan nama aplikasi yang ingin Anda laporkan data jejaknya menggunakan OpenTelemetry.
               var serviceName = "otlp-test";
               using var tracerProvider = Sdk.CreateTracerProviderBuilder()
                   .AddSource(serviceName)
                   .SetResourceBuilder(
                   ResourceBuilder.CreateDefault().AddService(serviceName))
                   .AddOtlpExporter(opt =>
                                    {
                                        // Ganti nilai parameter dengan titik akhir yang Anda peroleh di bagian "Prasyarat" dari topik ini.
                                        opt.Endpoint = new Uri("<endpoint>");
                                        // Laporkan data jejak melalui HTTP.
                                        opt.Protocol = OtlpExportProtocol.HttpProtobuf;
                                    })
                   .AddConsoleExporter() // Opsional. Ekspor data di 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 jalur saat ini:

   dotnet run

Metode 3: Gabungkan instrumentasi otomatis dengan instrumentasi manual

OpenTelemetry dapat mengunggah data jejak secara otomatis untuk puluhan kerangka kerja .NET. Untuk informasi lebih lanjut, lihat Instrumen Jejak.

1. Pergi ke direktori dotnet-demo/opentelemetry-demo/auto-demo dan buat aplikasi web menggunakan ASP.NET Core.

   Ganti <your-project-name> di kode dengan nama aplikasi Anda.

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

2. Unduh dependensi OpenTelemetry yang diperlukan untuk memantau aplikasi.

   dotnet add package OpenTelemetry.Exporter.Console # Ekspor data yang dikumpulkan di konsol.
   dotnet add package OpenTelemetry.Extensions.Hosting
   dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol # Ekspor data melalui Protokol OpenTelemetry (OTLP).

3. Unduh dependensi untuk instrumentasi otomatis.

   Unduh dependensi yang digunakan untuk menginstrumentasi aplikasi secara otomatis pada kerangka kerja ASP.NET Core. Saat aplikasi menerima permintaan HTTP, rentang akan dibuat secara otomatis dan kemudian dilaporkan. Untuk mengonfigurasi instrumentasi otomatis untuk aplikasi pada kerangka kerja lainnya, unduh dependensi terkait dari Instrumen Jejak.

   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> di kode dengan nama aplikasi dan nama host sebenarnya.

      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 untuk menginisialisasi OpenTelemetry.

      • Laporkan data melalui HTTP.

        Ganti <http_endpoint> di kode berikut dengan titik akhir yang diperoleh di bagian "Prasyarat" dari topik ini:

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

      • Laporkan data melalui gRPC.

        Ganti <grpc_endpoint> dan <token> di kode berikut dengan titik akhir dan token yang diperoleh di bagian "Prasyarat" dari topik ini:

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

   Kode Contoh Lengkap dari File Program.cs

   // 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 di konsol.
               .AddOtlpExporter(opt =>
               {
                   // Laporkan data melalui HTTP.
                   opt.Endpoint = new Uri("<http_endpoint>");
                   opt.Protocol = OtlpExportProtocol.HttpProtobuf;
   
                   // Laporkan data melalui gRPC.
                   // 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 aplikasi.
       public const string HostName = "<your-host-name>"; // Nama host.
       public static ActivitySource ActivitySource = new ActivitySource(ServiceName);
   }
                               

5. Jalankan perintah berikut di terminal untuk menjalankan proyek:

   dotnet run

   Contoh Keluaran Perintah:

   Peroleh URL di informasi yang dikembalikan. Contoh: 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. Kunjungi http://localhost:5107 di browser. Jika halaman berikut ditampilkan, data jejak telah dilaporkan ke konsol Managed Service for OpenTelemetry.

   

Lihat data pemantauan