Mengumpulkan jejak terdistribusi

Artikel
04/08/2023

Artikel ini berlaku untuk: ✔️ .NET Core 2.1 dan versi yang lebih baru .NET Framework 4.5 dan versi yang lebih baru ✔️

Kode berinstrumen dapat membuat Activity objek sebagai bagian dari jejak terdistribusi, tetapi informasi dalam objek ini perlu dikumpulkan ke dalam penyimpanan terpusat sehingga seluruh jejak dapat ditinjau nanti. Dalam tutorial ini, Anda akan mengumpulkan telemetri jejak terdistribusi dengan cara yang berbeda sehingga tersedia untuk mendiagnosis masalah aplikasi saat diperlukan. Lihat tutorial instrumentasi jika Anda perlu menambahkan instrumentasi baru.

Mengumpulkan jejak menggunakan OpenTelemetry

OpenTelemetry adalah proyek sumber terbuka netral vendor yang didukung oleh Cloud Native Computing Foundation yang bertujuan untuk menstandarkan pembuatan dan pengumpulan telemetri untuk perangkat lunak cloud-native. Dalam contoh ini, Anda akan mengumpulkan dan menampilkan informasi pelacakan terdistribusi di konsol. Untuk mempelajari cara mengonfigurasi OpenTelemetry untuk mengirim informasi di tempat lain, lihat panduan memulai OpenTelemetry.

contoh ASP.NET

Prasyarat

.NET Core 7.0 SDK atau versi yang lebih baru

Membuat aplikasi contoh

Pertama, buat aplikasi web ASP.NET baru untuk digunakan sebagai aplikasi demo.

dotnet new webapp

Aplikasi ini menampilkan halaman web, tetapi belum ada informasi pelacakan terdistribusi yang dikumpulkan jika kita menelusuri halaman web.

Mengonfigurasi koleksi

Untuk menggunakan OpenTelemetry, Anda perlu menambahkan referensi ke beberapa paket NuGet.

dotnet add package OpenTelemetry --version 1.4.0-rc1
dotnet add package OpenTelemetry.Exporter.Console --version 1.4.0-rc1
dotnet add package OpenTelemetry.Extensions.Hosting --version 1.4.0-rc1
dotnet add package OpenTelemetry.Instrumentation.AspNetCore --version 1.0.0-rc9.10

Catatan

Pada saat penulisan, build 1.4.0 Release Candidate 1 adalah versi terbaru dari OpenTelemetry yang tersedia. Setelah versi akhir tersedia, gunakan versi tersebut sebagai gantinya.

Selanjutnya, ubah kode sumber di Program.cs sehingga terlihat seperti ini:

using OpenTelemetry;
using OpenTelemetry.Trace;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddOpenTelemetry()
    .WithTracing(builder =>
    {
        builder.AddAspNetCoreInstrumentation();
        builder.AddConsoleExporter();
    }).StartWithHost();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Jalankan aplikasi dan gunakan browser web untuk menelusuri ke halaman web yang dihosting. Sekarang setelah Anda mengaktifkan pelacakan terdistribusi OpenTelemetry, Anda akan melihat informasi tentang permintaan web browser yang dicetak ke konsol:

Activity.TraceId:            9c4519ce65a667280daedb3808d376f0
Activity.SpanId:             727c6a8a6cff664f
Activity.TraceFlags:         Recorded
Activity.ActivitySourceName: Microsoft.AspNetCore
Activity.DisplayName:        /
Activity.Kind:               Server
Activity.StartTime:          2023-01-08T01:56:05.4529879Z
Activity.Duration:           00:00:00.1048255
Activity.Tags:
    net.host.name: localhost
    net.host.port: 5163
    http.method: GET
    http.scheme: http
    http.target: /
    http.url: http://localhost:5163/
    http.flavor: 1.1
    http.user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36 Edg/108.0.1462.76
    http.status_code: 200
Resource associated with Activity:
    service.name: unknown_service:demo

Semua konfigurasi OpenTelemetry terjadi di baris sumber baru yang dimulai dengan builder.Services.AddOpenTelemetry(). Anda digunakan .WithTracing(...) untuk mengaktifkan pelacakan terdistribusi. AddAspNetCoreInstrumentation() mengaktifkan OpenTelemetry untuk mengumpulkan semua Aktivitas pelacakan terdistribusi yang diproduksi oleh server web ASP.NET Core, dan AddConsoleExporter() menginstruksikan OpenTelemetry untuk mengirim informasi tersebut ke konsol. Untuk aplikasi yang kurang sepele, Anda dapat menambahkan lebih banyak pustaka instrumentasi untuk juga mengumpulkan pelacakan untuk kueri database atau permintaan HTTP keluar. Anda juga akan mengganti pengekspor konsol dengan pengekspor untuk Jaeger, Zipken, atau layanan pemantauan lain yang Anda pilih untuk digunakan.

Contoh aplikasi konsol

Prasyarat

.NET Core 2.1 SDK atau versi yang lebih baru

Membuat aplikasi contoh

Sebelum telemetri jejak terdistribusi dapat dikumpulkan, Anda perlu membuatnya. Seringkali instrumentasi ini ada di pustaka, tetapi untuk kesederhanaan, Anda akan membuat aplikasi kecil yang memiliki beberapa contoh instrumentasi menggunakan StartActivity. Pada titik ini, tidak ada koleksi yang terjadi, dan StartActivity() tidak memiliki efek samping dan mengembalikan null. Lihat tutorial instrumentasi untuk detail selengkapnya.

dotnet new console

Aplikasi yang menargetkan .NET 5 dan yang lebih baru sudah menyertakan API pelacakan terdistribusi yang diperlukan. Untuk aplikasi yang menargetkan versi .NET yang lebih lama, tambahkan paket NuGet System.Diagnostics.DiagnosticSource versi 5 atau yang lebih tinggi.

dotnet add package System.Diagnostics.DiagnosticSource

Ganti konten Program.cs yang dihasilkan dengan sumber contoh ini:

using System;
using System.Diagnostics;
using System.Threading.Tasks;

namespace Sample.DistributedTracing
{
    class Program
    {
        static ActivitySource s_source = new ActivitySource("Sample.DistributedTracing");

        static async Task Main(string[] args)
        {
            await DoSomeWork();
            Console.WriteLine("Example work done");
        }

        static async Task DoSomeWork()
        {
            using (Activity a = s_source.StartActivity("SomeWork"))
            {
                await StepOne();
                await StepTwo();
            }
        }

        static async Task StepOne()
        {
            using (Activity a = s_source.StartActivity("StepOne"))
            {
                await Task.Delay(500);
            }
        }

        static async Task StepTwo()
        {
            using (Activity a = s_source.StartActivity("StepTwo"))
            {
                await Task.Delay(1000);
            }
        }
    }
}

Menjalankan aplikasi belum mengumpulkan data pelacakan apa pun:

> dotnet run
Example work done

Mengonfigurasi koleksi

Tambahkan paket NuGet OpenTelemetry.Exporter.Console .

dotnet add package OpenTelemetry.Exporter.Console

Perbarui Program.cs dengan arahan OpenTelemetry using tambahan:

using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using System;
using System.Diagnostics;
using System.Threading.Tasks;

Perbarui Main() untuk membuat OpenTelemetry TracerProvider:

        public static async Task Main()
        {
            using var tracerProvider = Sdk.CreateTracerProviderBuilder()
                .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("MySample"))
                .AddSource("Sample.DistributedTracing")
                .AddConsoleExporter()
                .Build();

            await DoSomeWork();
            Console.WriteLine("Example work done");
        }

Sekarang aplikasi mengumpulkan informasi pelacakan terdistribusi dan menampilkannya ke konsol:

> dotnet run
Activity.Id:          00-7759221f2c5599489d455b84fa0f90f4-6081a9b8041cd840-01
Activity.ParentId:    00-7759221f2c5599489d455b84fa0f90f4-9a52f72c08a9d447-01
Activity.DisplayName: StepOne
Activity.Kind:        Internal
Activity.StartTime:   2021-03-18T10:46:46.8649754Z
Activity.Duration:    00:00:00.5069226
Resource associated with Activity:
    service.name: MySample
    service.instance.id: 909a4624-3b2e-40e4-a86b-4a2c8003219e

Activity.Id:          00-7759221f2c5599489d455b84fa0f90f4-d2b283db91cf774c-01
Activity.ParentId:    00-7759221f2c5599489d455b84fa0f90f4-9a52f72c08a9d447-01
Activity.DisplayName: StepTwo
Activity.Kind:        Internal
Activity.StartTime:   2021-03-18T10:46:47.3838737Z
Activity.Duration:    00:00:01.0142278
Resource associated with Activity:
    service.name: MySample
    service.instance.id: 909a4624-3b2e-40e4-a86b-4a2c8003219e

Activity.Id:          00-7759221f2c5599489d455b84fa0f90f4-9a52f72c08a9d447-01
Activity.DisplayName: SomeWork
Activity.Kind:        Internal
Activity.StartTime:   2021-03-18T10:46:46.8634510Z
Activity.Duration:    00:00:01.5402045
Resource associated with Activity:
    service.name: MySample
    service.instance.id: 909a4624-3b2e-40e4-a86b-4a2c8003219e

Example work done

Sumber

Dalam kode contoh, Anda memanggil AddSource("Sample.DistributedTracing") sehingga OpenTelemetry akan mengambil Aktivitas yang dihasilkan oleh ActivitySource yang sudah ada dalam kode:

static ActivitySource s_source = new ActivitySource("Sample.DistributedTracing");

Telemetri dari ActivitySource apa pun dapat ditangkap dengan memanggil AddSource() dengan nama sumber.

Eksportir

Pengekspor konsol sangat membantu untuk contoh cepat atau pengembangan lokal tetapi dalam penyebaran produksi Anda mungkin ingin mengirim jejak ke penyimpanan terpusat. OpenTelemetry mendukung berbagai tujuan menggunakan eksportir yang berbeda. Untuk informasi selengkapnya tentang mengonfigurasi OpenTelemetry, lihat panduan memulai OpenTelemetry.

Mengumpulkan jejak menggunakan Application Insights

Telemetri pelacakan terdistribusi secara otomatis diambil setelah mengonfigurasi Application Insights SDK untuk aplikasi ASP.NET atau ASP.NET Core , atau dengan mengaktifkan instrumentasi tanpa kode.

Untuk informasi selengkapnya, lihat dokumentasi pelacakan terdistribusi Application Insights.

Catatan

Saat ini, Application Insights hanya mendukung pengumpulan instrumentasi Aktivitas terkenal tertentu dan mengabaikan Aktivitas baru yang ditambahkan pengguna. Application Insights menawarkan TrackDependency sebagai API khusus vendor untuk menambahkan informasi pelacakan terdistribusi kustom.

Mengumpulkan jejak menggunakan logika kustom

Pengembang bebas membuat logika pengumpulan yang disesuaikan sendiri untuk data pelacakan Aktivitas. Contoh ini mengumpulkan telemetri menggunakan System.Diagnostics.ActivityListener API yang disediakan oleh .NET dan mencetaknya ke konsol.

Prasyarat

.NET Core 2.1 SDK atau versi yang lebih baru

Membuat aplikasi contoh

Pertama, Anda akan membuat aplikasi contoh yang memiliki beberapa instrumentasi jejak terdistribusi tetapi tidak ada data jejak yang dikumpulkan.

dotnet new console

dotnet add package System.Diagnostics.DiagnosticSource

Ganti konten Program.cs yang dihasilkan dengan sumber contoh ini:

using System;
using System.Diagnostics;
using System.Threading.Tasks;

namespace Sample.DistributedTracing
{
    class Program
    {
        static ActivitySource s_source = new ActivitySource("Sample.DistributedTracing");

        static async Task Main(string[] args)
        {
            await DoSomeWork();
            Console.WriteLine("Example work done");
        }

        static async Task DoSomeWork()
        {
            using (Activity a = s_source.StartActivity("SomeWork"))
            {
                await StepOne();
                await StepTwo();
            }
        }

        static async Task StepOne()
        {
            using (Activity a = s_source.StartActivity("StepOne"))
            {
                await Task.Delay(500);
            }
        }

        static async Task StepTwo()
        {
            using (Activity a = s_source.StartActivity("StepTwo"))
            {
                await Task.Delay(1000);
            }
        }
    }
}

Menjalankan aplikasi belum mengumpulkan data pelacakan apa pun:

> dotnet run
Example work done

Menambahkan kode untuk mengumpulkan jejak

Perbarui Main() dengan kode ini:

        static async Task Main(string[] args)
        {
            Activity.DefaultIdFormat = ActivityIdFormat.W3C;
            Activity.ForceDefaultIdFormat = true;

            Console.WriteLine("         {0,-15} {1,-60} {2,-15}", "OperationName", "Id", "Duration");
            ActivitySource.AddActivityListener(new ActivityListener()
            {
                ShouldListenTo = (source) => true,
                Sample = (ref ActivityCreationOptions<ActivityContext> options) => ActivitySamplingResult.AllDataAndRecorded,
                ActivityStarted = activity => Console.WriteLine("Started: {0,-15} {1,-60}", activity.OperationName, activity.Id),
                ActivityStopped = activity => Console.WriteLine("Stopped: {0,-15} {1,-60} {2,-15}", activity.OperationName, activity.Id, activity.Duration)
            });

            await DoSomeWork();
            Console.WriteLine("Example work done");
        }

Output sekarang mencakup pengelogan:

> dotnet run
         OperationName   Id                                                           Duration
Started: SomeWork        00-bdb5faffc2fc1548b6ba49a31c4a0ae0-c447fb302059784f-01
Started: StepOne         00-bdb5faffc2fc1548b6ba49a31c4a0ae0-a7c77a4e9a02dc4a-01
Stopped: StepOne         00-bdb5faffc2fc1548b6ba49a31c4a0ae0-a7c77a4e9a02dc4a-01      00:00:00.5093849
Started: StepTwo         00-bdb5faffc2fc1548b6ba49a31c4a0ae0-9210ad536cae9e4e-01
Stopped: StepTwo         00-bdb5faffc2fc1548b6ba49a31c4a0ae0-9210ad536cae9e4e-01      00:00:01.0111847
Stopped: SomeWork        00-bdb5faffc2fc1548b6ba49a31c4a0ae0-c447fb302059784f-01      00:00:01.5236391
Example work done

Mengatur DefaultIdFormat dan ForceDefaultIdFormat bersifat opsional tetapi membantu memastikan sampel menghasilkan output serupa pada versi runtime .NET yang berbeda. .NET 5 menggunakan format ID W3C TraceContext secara default tetapi versi .NET sebelumnya default menggunakan Hierarchical format ID. Untuk informasi selengkapnya, lihat ID Aktivitas.

System.Diagnostics.ActivityListener digunakan untuk menerima panggilan balik selama masa pakai Aktivitas.

ShouldListenTo - Setiap Aktivitas dikaitkan dengan ActivitySource, yang bertindak sebagai namespace layanan dan produsernya. Panggilan balik ini dipanggil sekali untuk setiap ActivitySource dalam proses. Kembalikan true jika Anda tertarik untuk melakukan pengambilan sampel atau diberi tahu tentang peristiwa mulai/berhenti untuk Aktivitas yang dihasilkan oleh sumber ini.
Sample - Secara default StartActivity tidak membuat objek Aktivitas kecuali beberapa ActivityListener menunjukkan bahwa objek tersebut harus diambil sampelnya. AllDataAndRecorded Mengembalikan menunjukkan bahwa Aktivitas harus dibuat, IsAllDataRequested harus diatur ke true, dan ActivityTraceFlags akan memiliki bendera yang Recorded ditetapkan. IsAllDataRequested dapat diamati oleh kode berinstrumen sebagai petunjuk bahwa pendengar ingin memastikan bahwa informasi Aktivitas tambahan seperti Tag dan Peristiwa diisi. Bendera Yang direkam dikodekan dalam ID TraceContext W3C dan merupakan petunjuk untuk proses lain yang terlibat dalam jejak terdistribusi bahwa jejak ini harus diambil sampelnya.
ActivityStarted dan ActivityStopped dipanggil ketika Aktivitas dimulai dan dihentikan masing-masing. Panggilan balik ini memberikan kesempatan untuk merekam informasi yang relevan tentang Aktivitas atau berpotensi memodifikasinya. Ketika Aktivitas baru saja dimulai, sebagian besar data mungkin masih tidak lengkap dan akan diisi sebelum Aktivitas berhenti.

Setelah ActivityListener dibuat dan panggilan balik diisi, panggilan ActivitySource.AddActivityListener(ActivityListener) dimulai memanggil panggilan balik. Panggil ActivityListener.Dispose() untuk menghentikan alur panggilan balik. Ketahuilah bahwa dalam kode multi-utas, pemberitahuan panggilan balik yang sedang berlangsung dapat diterima saat Dispose() sedang berjalan atau bahkan tak lama setelah dikembalikan.

Bagikan melalui

Mengumpulkan jejak terdistribusi

Mengumpulkan jejak menggunakan OpenTelemetry

contoh ASP.NET

Prasyarat

Membuat aplikasi contoh

Mengonfigurasi koleksi

Contoh aplikasi konsol

Prasyarat

Membuat aplikasi contoh

Mengonfigurasi koleksi

Sumber

Eksportir

Mengumpulkan jejak menggunakan Application Insights

Mengumpulkan jejak menggunakan logika kustom

Prasyarat

Membuat aplikasi contoh

Menambahkan kode untuk mengumpulkan jejak

Sumber Daya Tambahan: