Bagikan melalui

Contoh: Gunakan OpenTelemetry dengan Prometheus, Grafana, dan Jaeger

Contoh ini menggunakan Prometheus untuk koleksi metrik, Grafana untuk membuat dasbor, dan Jaeger untuk menampilkan pelacakan terdistribusi.

1. Buat proyek

Buat proyek API web sederhana dengan menggunakan templat ASP.NET Core Empty di Visual Studio atau perintah .NET CLI berikut:

dotnet new web

2. Tambahkan metrik dan definisi aktivitas

Kode berikut mendefinisikan metrik baru (greetings.count) untuk berapa kali API telah dipanggil, dan sumber aktivitas baru (OtPrGrYa.Example).

// Custom metrics for the application
var greeterMeter = new Meter("OtPrGrYa.Example", "1.0.0");
var countGreetings = greeterMeter.CreateCounter<int>("greetings.count", description: "Counts the number of greetings");

// Custom ActivitySource for the application
var greeterActivitySource = new ActivitySource("OtPrGrJa.Example");

3. Buat titik akhir API

app.MapGet("/", SendGreeting);

async Task<string> SendGreeting(ILogger<Program> logger)
{
    // Create a new Activity scoped to the method
    using var activity = greeterActivitySource.StartActivity("GreeterActivity");

    // Log a message
    logger.LogInformation("Sending greeting");

    // Increment the custom counter
    countGreetings.Add(1);

    // Add a tag to the Activity
    activity?.SetTag("greeting", "Hello World!");

    return "Hello World!";
}

Catatan

Definisi API tidak menggunakan apa pun khusus untuk OpenTelemetry. Ini menggunakan API .NET untuk pengamatan.

4. Referensi paket OpenTelemetry

Gunakan Manajer Paket NuGet atau baris perintah untuk menambahkan paket NuGet berikut:

<ItemGroup>
    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Exporter.Prometheus.AspNetCore" Version="1.9.0-beta.2" />
    <PackageReference Include="OpenTelemetry.Exporter.Zipkin" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.9.0" />
</ItemGroup>

Catatan

Gunakan versi terbaru, karena API OTel terus berkembang.

5. Mengonfigurasi OpenTelemetry dengan penyedia yang benar

var tracingOtlpEndpoint = builder.Configuration["OTLP_ENDPOINT_URL"];
var otel = builder.Services.AddOpenTelemetry();

// Configure OpenTelemetry Resources with the application name
otel.ConfigureResource(resource => resource
    .AddService(serviceName: builder.Environment.ApplicationName));

// Add Metrics for ASP.NET Core and our custom metrics and export to Prometheus
otel.WithMetrics(metrics => metrics
    // Metrics provider from OpenTelemetry
    .AddAspNetCoreInstrumentation()
    .AddMeter(greeterMeter.Name)
    // Metrics provides by ASP.NET Core in .NET 8
    .AddMeter("Microsoft.AspNetCore.Hosting")
    .AddMeter("Microsoft.AspNetCore.Server.Kestrel")
    // Metrics provided by System.Net libraries
    .AddMeter("System.Net.Http")
    .AddMeter("System.Net.NameResolution")
    .AddPrometheusExporter());

// Add Tracing for ASP.NET Core and our custom ActivitySource and export to Jaeger
otel.WithTracing(tracing =>
{
    tracing.AddAspNetCoreInstrumentation();
    tracing.AddHttpClientInstrumentation();
    tracing.AddSource(greeterActivitySource.Name);
    if (tracingOtlpEndpoint != null)
    {
        tracing.AddOtlpExporter(otlpOptions =>
         {
             otlpOptions.Endpoint = new Uri(tracingOtlpEndpoint);
         });
    }
    else
    {
        tracing.AddConsoleExporter();
    }
});

Kode ini menggunakan instrumentasi ASP.NET Core untuk mendapatkan metrik dan aktivitas dari ASP.NET Core. Ini juga mendaftarkan Metrics penyedia dan ActivitySource untuk metrik dan pelacakan masing-masing.

Kode ini menggunakan pengekspor Prometheus untuk metrik, yang menggunakan ASP.NET Core untuk menghosting titik akhir, jadi Anda juga perlu menambahkan:

// Configure the Prometheus scraping endpoint
app.MapPrometheusScrapingEndpoint();

6. Jalankan proyek

Jalankan proyek lalu akses API dengan browser atau curl.

curl -k http://localhost:7275

Setiap kali Anda meminta halaman, halaman akan meningkatkan jumlah untuk jumlah salam yang telah dibuat. Anda dapat mengakses titik akhir metrik menggunakan url dasar yang sama, dengan jalur /metrics.

6.1 Output log

Pernyataan pengelogan dari kode adalah output menggunakan ILogger. Secara default, Penyedia Konsol diaktifkan sehingga output diarahkan ke konsol.

Ada beberapa opsi tentang bagaimana log dapat keluar dari .NET:

  • stdout dan stderr output dialihkan ke file log oleh sistem kontainer seperti Kubernetes.
  • Menggunakan pustaka pengelogan yang akan diintegrasikan dengan ILogger, ini termasuk Serilog atau NLog.
  • Menggunakan penyedia pengelogan untuk OTel seperti OTLP atau pengekspor Azure Monitor yang ditunjukkan lebih lanjut di bawah ini.

6.2 Mengakses metrik

Anda dapat mengakses metrik menggunakan /metrics titik akhir.

curl -k https://localhost:7275/
Hello World!

curl -k https://localhost:7275/metrics
# TYPE greetings_count counter
# HELP greetings_count Counts the number of greetings
greetings_count 1 1686894204856

# TYPE current_connections gauge
# HELP current_connections Number of connections that are currently active on the server.
current_connections{endpoint="127.0.0.1:7275"} 1 1686894204856
current_connections{endpoint="[::1]:7275"} 0 1686894204856
current_connections{endpoint="[::1]:5212"} 1 1686894204856
...

Output metrik adalah rekam jepret metrik pada saat titik akhir diminta. Hasilnya disediakan dalam format eksposisi Prometheus, yang dapat dibaca manusia tetapi lebih dipahami oleh Prometheus. Topik itu dibahas di tahap berikutnya.

6.3 Mengakses pelacakan

Jika Anda melihat konsol untuk server, Anda akan melihat output dari pengekspor jejak konsol, yang menghasilkan informasi dalam format yang dapat dibaca manusia. Ini akan menunjukkan dua aktivitas, satu dari kustom ActivitySourceAnda , dan yang lainnya dari ASP.NET Core:

Activity.TraceId:            2e00dd5e258d33fe691b965607b91d18
Activity.SpanId:             3b7a891f55b97f1a
Activity.TraceFlags:         Recorded
Activity.ParentSpanId:       645071fd0011faac
Activity.ActivitySourceName: OtPrGrYa.Example
Activity.DisplayName:        GreeterActivity
Activity.Kind:               Internal
Activity.StartTime:          2023-06-16T04:50:26.7675469Z
Activity.Duration:           00:00:00.0023974
Activity.Tags:
    greeting: Hello World!
Resource associated with Activity:
    service.name: OTel-Prometheus-Grafana-Jaeger
    service.instance.id: e1afb619-bc32-48d8-b71f-ee196dc2a76a
    telemetry.sdk.name: opentelemetry
    telemetry.sdk.language: dotnet
    telemetry.sdk.version: 1.5.0

Activity.TraceId:            2e00dd5e258d33fe691b965607b91d18
Activity.SpanId:             645071fd0011faac
Activity.TraceFlags:         Recorded
Activity.ActivitySourceName: Microsoft.AspNetCore
Activity.DisplayName:        /
Activity.Kind:               Server
Activity.StartTime:          2023-06-16T04:50:26.7672615Z
Activity.Duration:           00:00:00.0121259
Activity.Tags:
    net.host.name: localhost
    net.host.port: 7275
    http.method: GET
    http.scheme: https
    http.target: /
    http.url: https://localhost:7275/
    http.flavor: 1.1
    http.user_agent: curl/8.0.1
    http.status_code: 200
Resource associated with Activity:
    service.name: OTel-Prometheus-Grafana-Jaeger
    service.instance.id: e1afb619-bc32-48d8-b71f-ee196dc2a76a
    telemetry.sdk.name: opentelemetry
    telemetry.sdk.language: dotnet
    telemetry.sdk.version: 1.5.0

Yang pertama adalah aktivitas kustom dalam yang Anda buat. Yang kedua dibuat oleh ASP.NET untuk permintaan dan menyertakan tag untuk properti permintaan HTTP. Anda akan melihat bahwa keduanya memiliki yang sama TraceId, yang mengidentifikasi satu transaksi dan dalam sistem terdistribusi dapat digunakan untuk menghubungkan jejak dari setiap layanan yang terlibat dalam transaksi. ID ditransmisikan sebagai header HTTP. ASP.NET Core menetapkan TraceId jika tidak ada yang ada saat menerima permintaan. HttpClient menyertakan header secara default pada permintaan keluar. Setiap aktivitas memiliki SpanId, yang merupakan kombinasi dari TraceId dan SpanId yang secara unik mengidentifikasi setiap aktivitas. Aktivitas Greeter ini diinduk ke aktivitas HTTP melalui ParentSpanId, yang memetakan ke SpanId aktivitas HTTP.

Pada tahap selanjutnya, Anda akan mengumpankan data ini ke Jaeger untuk memvisualisasikan jejak terdistribusi.

7. Kumpulkan metrik dengan Prometheus

Prometheus adalah kumpulan metrik, agregasi, dan sistem database rangkaian waktu. Anda mengonfigurasinya dengan titik akhir metrik untuk setiap layanan dan secara berkala mengikis nilai dan menyimpannya dalam database rangkaian waktunya. Anda kemudian dapat menganalisis dan memprosesnya sesuai kebutuhan.

Data metrik yang diekspos dalam format Prometheus adalah rekam jepret titik waktu metrik proses. Setiap kali permintaan dibuat ke titik akhir metrik, permintaan akan melaporkan nilai saat ini. Meskipun nilai saat ini menarik, nilai tersebut menjadi lebih berharga jika dibandingkan dengan nilai historis untuk melihat tren dan mendeteksi apakah nilai anomali. Umumnya, layanan memiliki lonjakan penggunaan berdasarkan waktu acara hari atau dunia, seperti belanja liburan. Dengan membandingkan nilai dengan tren historis, Anda dapat mendeteksi apakah nilai tersebut abnormal, atau jika metrik perlahan-lahan semakin memburuk dari waktu ke waktu.

Proses ini tidak menyimpan riwayat rekam jepret metrik ini. Menambahkan kemampuan tersebut ke proses bisa menjadi sumber daya intensif. Selain itu, dalam sistem terdistribusi Anda biasanya memiliki beberapa instans dari setiap simpul, jadi Anda ingin dapat mengumpulkan metrik dari semuanya dan kemudian menggabungkan dan membandingkan dengan nilai historisnya.

7.1 Menginstal dan mengonfigurasi Prometheus

Unduh Prometheus untuk platform Anda dari https://prometheus.io/download/ dan ekstrak konten unduhan.

Lihat bagian atas output server anda yang sedang berjalan untuk mendapatkan nomor port untuk titik akhir http . Contohnya:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7275
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5212

Ubah file konfigurasi PROmetheus YAML untuk menentukan port untuk titik akhir pengikisan HTTP Anda dan atur interval pengikisan yang lebih rendah. Contohnya:

  scrape_configs:
  # The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
  - job_name: "prometheus"

    # metrics_path defaults to '/metrics'
    # scheme defaults to 'http'.

    scrape_interval: 1s # poll very quickly for a more responsive demo
    static_configs:
      - targets: ["localhost:5212"]

Mulai Prometheus, dan lihat output untuk port yang dijalankannya, biasanya 9090:

>prometheus.exe
...
ts=2023-06-16T05:29:02.789Z caller=web.go:562 level=info component=web msg="Start listening for connections" address=0.0.0.0:9090

Buka URL ini di browser Anda. Di UI Prometheus, Anda sekarang dapat mengkueri metrik Anda. Gunakan tombol yang disorot dalam gambar berikut untuk membuka penjelajah metrik, yang menunjukkan semua metrik yang tersedia.

Penjelajah Metrik Prometheus

greetings_count Pilih metrik untuk melihat grafik nilai.

Grafik greetings_count

8. Gunakan Grafana untuk membuat dasbor metrik

Grafana adalah produk dasbor yang dapat membuat dasbor dan peringatan berdasarkan Prometheus atau sumber data lainnya.

Unduh dan instal grafana versi OSS dari https://grafana.com/oss/grafana/ mengikuti instruksi untuk platform Anda. Setelah diinstal, Grafana biasanya dijalankan pada port 3000, jadi buka http://localhost:3000 di browser Anda. Anda harus masuk; nama pengguna dan kata sandi default keduanya adalah admin.

Dari menu hamburger pilih koneksi, lalu masukkan teks prometheus untuk memilih jenis titik akhir Anda. Pilih Buat sumber data Prometheus untuk menambahkan sumber data baru.

Koneksi Grafana ke prometheus

Anda perlu mengatur properti berikut:

  • URL server Prometheus: http://localhost:9090/ mengubah port sebagaimana berlaku

Pilih Simpan & Uji untuk memverifikasi konfigurasi.

Setelah mendapatkan pesan sukses, Anda dapat mengonfigurasi dasbor. Klik tautan bangun dasbor yang ditampilkan di popup untuk pesan keberhasilan.

Pilih Tambahkan Visualisasi, lalu pilih sumber data Prometheus yang baru saja Anda tambahkan sebagai sumber data.

Perancang panel dasbor akan muncul. Di bagian bawah layar, Anda dapat menentukan kueri.

Kueri Grafana menggunakan greetings_count

greetings_count Pilih metrik, lalu pilih Jalankan Kueri untuk melihat hasilnya.

Dengan Grafana, Anda dapat merancang dasbor canggih yang akan melacak sejumlah metrik.

Setiap metrik di .NET dapat memiliki dimensi tambahan, yang merupakan pasangan kunci-nilai yang dapat digunakan untuk mempartisi data. Semua metrik ASP.NET menampilkan sejumlah dimensi yang berlaku untuk penghitung. Misalnya, penghitung current-requests dari Microsoft.AspNetCore.Hosting memiliki dimensi berikut:

Atribut Tipe Deskripsi Contoh Kehadiran
method string Metode permintaan HTTP. GET; POST; HEAD Selalu
scheme string Skema URI mengidentifikasi protokol yang digunakan. http; https Selalu
host string Nama server HTTP lokal yang menerima permintaan. localhost Selalu
port int Port server HTTP lokal yang menerima permintaan. 8080 Ditambahkan jika bukan default (80 untuk http atau 443 untuk https)

Grafik di Grafana biasanya dipartisi berdasarkan setiap kombinasi dimensi yang unik. Dimensi dapat digunakan dalam kueri Grafana untuk memfilter atau menggabungkan data. Misalnya, jika Anda membuat grafik current_requests, Anda akan melihat nilai yang dipartisi berdasarkan setiap kombinasi dimensi. Untuk memfilter hanya berdasarkan host, tambahkan operasi Sum dan gunakan host sebagai nilai label.

Grafana current_requests oleh host

9. Pelacakan terdistribusi dengan Jaeger

Pada langkah 6, Anda melihat bahwa informasi pelacakan terdistribusi sedang diekspos ke konsol. Informasi ini melacak unit kerja dengan aktivitas. Beberapa aktivitas dibuat secara otomatis oleh platform, seperti satu per ASP.NET untuk mewakili penanganan permintaan, dan pustaka dan kode aplikasi juga dapat membuat aktivitas. Contoh salam memiliki Greeter aktivitas. Aktivitas berkorelasi menggunakan TraceIdtag , , SpanIddan ParentId .

Setiap proses dalam sistem terdistribusi menghasilkan aliran informasi aktivitasnya sendiri, dan seperti metrik, Anda memerlukan sistem untuk mengumpulkan, menyimpan, dan menghubungkan aktivitas untuk dapat memvisualisasikan pekerjaan yang dilakukan untuk setiap transaksi. Jaeger adalah proyek sumber terbuka untuk mengaktifkan koleksi dan visualisasi ini.

Unduh arsip distribusi biner terbaru Jaeger untuk platform Anda dari https://www.jaegertracing.io/download/.

Kemudian, ekstrak unduhan ke lokasi lokal yang mudah diakses. Jalankan jaeger-all-in-one(.exe) yang dapat dieksekusi:

./jaeger-all-in-one --collector.otlp.enabled

Lihat output konsol untuk menemukan port tempat konsol mendengarkan lalu lintas OTLP melalui gRPC. Contohnya:

{"level":"info","ts":1686963686.3854616,"caller":"otlpreceiver@v0.78.2/otlp.go:83","msg":"Starting GRPC server","endpoint":"0.0.0.0:4317"}

Output ini memberi tahu Anda bahwa ia mendengarkan di 0.0.0.0:4317, sehingga Anda dapat mengonfigurasi port tersebut sebagai tujuan pengekspor OTLP Anda.

AppSettings.json Buka file untuk proyek kami, dan tambahkan baris berikut, mengubah port jika berlaku.

"OTLP_ENDPOINT_URL" :  "http://localhost:4317/"

Mulai ulang proses penyambutan sehingga dapat mengambil perubahan properti dan mulai mengarahkan informasi pelacakan ke Jaeger.

Sekarang, Anda harus dapat melihat UI Jaeger di http://localhost:16686/ dari browser web.

Kueri Jaeger untuk jejak

Untuk melihat daftar jejak, pilih OTel-Prometheus-grafana-Jaeger dari menu dropdown Layanan . Memilih jejak harus menampilkan bagan gantt aktivitas sebagai bagian dari jejak tersebut. Mengklik setiap operasi menunjukkan detail selengkapnya tentang aktivitas.

Detail Operasi Jaeger

Dalam sistem terdistribusi, Anda ingin mengirim jejak dari semua proses ke instalasi Jaeger yang sama sehingga dapat menghubungkan transaksi di seluruh sistem.

Anda dapat membuat aplikasi Anda sedikit lebih menarik dengan membuatnya melakukan panggilan HTTP ke dirinya sendiri.

  • HttpClient Menambahkan pabrik ke aplikasi

    builder.Services.AddHttpClient();

  • Menambahkan titik akhir baru untuk melakukan panggilan salam berlapis

    app.MapGet("/NestedGreeting", SendNestedGreeting);

  • Terapkan titik akhir sehingga melakukan panggilan HTTP yang juga dapat dilacak. Dalam hal ini, ia memanggil kembali ke dirinya sendiri dalam perulangan buatan (benar-benar hanya berlaku untuk skenario demo).

    async Task SendNestedGreeting(int nestlevel, ILogger<Program> logger, HttpContext context, IHttpClientFactory clientFactory)
{
    // Create a new Activity scoped to the method
    using var activity = greeterActivitySource.StartActivity("GreeterActivity");

    if (nestlevel <= 5)
    {
        // Log a message
        logger.LogInformation("Sending greeting, level {nestlevel}", nestlevel);

        // Increment the custom counter
        countGreetings.Add(1);

        // Add a tag to the Activity
        activity?.SetTag("nest-level", nestlevel);

        await context.Response.WriteAsync($"Nested Greeting, level: {nestlevel}\r\n");

        if (nestlevel > 0)
        {
            var request = context.Request;
            var url = new Uri($"{request.Scheme}://{request.Host}{request.Path}?nestlevel={nestlevel - 1}");

            // Makes an http call passing the activity information as http headers
            var nestedResult = await clientFactory.CreateClient().GetStringAsync(url);
            await context.Response.WriteAsync(nestedResult);
        }
    }
    else
    {
        // Log a message
        logger.LogError("Greeting nest level {nestlevel} too high", nestlevel);
        await context.Response.WriteAsync("Nest level too high, max is 5");
    }
}

Ini menghasilkan grafik yang lebih menarik dengan bentuk piramida untuk permintaan, karena setiap tingkat menunggu respons dari panggilan sebelumnya.

Hasil dependensi berlapis Jaeger