Metrik ASP.NET Core

Metrik adalah pengukuran numerik yang dilaporkan dari waktu ke waktu. Gunakan untuk memantau kesehatan aplikasi dan menghasilkan pemberitahuan. Misalnya, layanan web mungkin melacak berapa banyak:

• Permintaan yang diterimanya per detik.
• Milidetik yang diperlukan untuk merespons.
• Respons yang dikirimnya saat terjadi kesalahan.

Laporkan metrik ini ke sistem pemantauan secara berkala. Siapkan dasbor untuk melihat metrik dan membuat pemberitahuan untuk memberi tahu orang tentang masalah. Jika layanan web dimaksudkan untuk menanggapi permintaan dalam waktu 400 md dan mulai merespons dalam 600 ms, sistem pemantauan dapat memberi tahu staf operasi bahwa respons aplikasi lebih lambat dari biasanya.

Daftar komprehensif semua instrumen bersama dengan atributnya dijelaskan dalam metrik bawaan ASP.NET Core.

Menggunakan metrik

Menggunakan metrik melibatkan hal berikut:

• Instrumentasi: Kode di pustaka .NET mengambil pengukuran dan mengaitkan pengukuran ini dengan nama metrik. .NET dan ASP.NET Core mencakup banyak metrik bawaan.
• Koleksi dan penyimpanan: Aplikasi .NET mengonfigurasi metrik bernama untuk dikirimkan dari aplikasi untuk penyimpanan dan analisis eksternal. Beberapa alat mungkin melakukan konfigurasi di luar aplikasi dengan menggunakan file konfigurasi atau alat UI.
• Visualisasi: Alat yang dapat menampilkan metrik dalam format yang dapat dibaca manusia. Misalnya, Grafana dan Prometheus.
• Memperingatkan: Alat yang menyediakan pemberitahuan saat metrik melebihi ambang batas. Misalnya, jika waktu respons rata-rata untuk layanan web melebihi 400 ms, pemberitahuan dapat dikirim ke staf operasi.
• Analisis: Alat yang dapat menganalisis metrik dari waktu ke waktu. Alat ini sering kali merupakan dasbor berbasis web yang dapat disesuaikan untuk menampilkan metrik terpenting untuk aplikasi tertentu.

Kode berinstrumen dapat merekam pengukuran numerik, tetapi untuk membuat metrik yang berguna untuk pemantauan, Anda perlu mengagregasi, mengirimkan, dan menyimpan pengukuran. Proses agregasi, transmisi, dan penyimpanan data disebut pengumpulan. Tutorial ini menunjukkan beberapa contoh pengumpulan dan tampilan metrik:

• Mengisi metrik pada Grafana dengan OpenTelemetry dan Prometheus.
• Menampilkan metrik secara real time dengan dotnet-counters

Anda juga dapat mengaitkan pengukuran dengan pasangan kunci-nilai yang disebut tag yang memungkinkan Anda mengategorikan data untuk analisis. Untuk informasi selengkapnya, lihat Metrik multi-dimensi.

Membuat aplikasi pemula

Buat aplikasi ASP.NET Core baru dengan perintah berikut:

dotnet new web -o WebMetric
cd WebMetric
dotnet add package OpenTelemetry.Exporter.Prometheus.AspNetCore --prerelease
dotnet add package OpenTelemetry.Extensions.Hosting

Ganti isi Program.cs dengan kode berikut:

using OpenTelemetry.Metrics;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry()
    .WithMetrics(builder =>
    {
        builder.AddPrometheusExporter();

        builder.AddMeter("Microsoft.AspNetCore.Hosting",
                         "Microsoft.AspNetCore.Server.Kestrel");
        builder.AddView("http.server.request.duration",
            new ExplicitBucketHistogramConfiguration
            {
                Boundaries = new double[] { 0, 0.005, 0.01, 0.025, 0.05,
                       0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 }
            });
    });
var app = builder.Build();

app.MapPrometheusScrapingEndpoint();

app.MapGet("/", () => "Hello OpenTelemetry! ticks:"
                     + DateTime.Now.Ticks.ToString()[^3..]);

app.Run();

Melihat metrik dengan dotnet-counters

dotnet-counters adalah alat command-line yang dapat melihat metrik langsung untuk aplikasi .NET sesuai permintaan. Ini tidak memerlukan penyiapan, membuatnya berguna untuk investigasi ad-hoc atau memverifikasi bahwa instrumentasi metrik berfungsi. Ini berfungsi dengan API berbasis System.Diagnostics.Metrics dan EventCounters.

Jika alat dotnet-counters belum diinstal, jalankan perintah berikut:

dotnet tool update -g dotnet-counters

Saat aplikasi pengujian berjalan, luncurkan penghitung dotnet. Perintah berikut menunjukkan contoh dotnet-counters pemantauan semua metrik dari Microsoft.AspNetCore.Hosting pengukur.

dotnet-counters monitor -n WebMetric --counters Microsoft.AspNetCore.Hosting

Output yang mirip dengan berikut ini ditampilkan:

Press p to pause, r to resume, q to quit.
    Status: Running

[Microsoft.AspNetCore.Hosting]
    http-server-current-requests
        host=localhost,method=GET,port=5045,scheme=http                    0
    http-server-request-duration (s)
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0.001
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0.001
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0.001
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0

Untuk informasi selengkapnya, lihat dotnet-counters.

Memperkaya metrik permintaan ASP.NET Core

ASP.NET Core memiliki banyak metrik bawaan. http.server.request.duration metrik:

• Mencatat durasi permintaan HTTP di server.
• Mengambil informasi permintaan dalam tag, seperti rute yang cocok dan kode status respons.

Metrik http.server.request.duration mendukung pengayaan tag melalui IHttpMetricsTagsFeature. Pengayaan adalah ketika pustaka atau aplikasi menambahkan tagnya sendiri ke metrik. Fitur ini berguna jika aplikasi ingin menambahkan kategorisasi kustom ke dasbor atau pemberitahuan yang dibangun dengan metrik.

using Microsoft.AspNetCore.Http.Features;

var builder = WebApplication.CreateBuilder();
var app = builder.Build();

app.Use(async (context, next) =>
{
    var tagsFeature = context.Features.Get<IHttpMetricsTagsFeature>();
    if (tagsFeature != null)
    {
        var source = context.Request.Query["utm_medium"].ToString() switch
        {
            "" => "none",
            "social" => "social",
            "email" => "email",
            "organic" => "organic",
            _ => "other"
        };
        tagsFeature.Tags.Add(new KeyValuePair<string, object?>("mkt_medium", source));
    }

    await next.Invoke();
});

app.MapGet("/", () => "Hello World!");

app.Run();

Contoh sebelumnya:

• Menambahkan middleware untuk memperkaya metrik permintaan ASP.NET Core.
• Mengambil IHttpMetricsTagsFeature dari HttpContext. Fitur ini hanya tersedia dalam konteks jika seseorang memantau metrik tersebut. Pastikan IHttpMetricsTagsFeature bukan null sebelum menggunakannya.
• Menambahkan tag kustom yang berisi sumber pemasaran permintaan ke http.server.request.duration metrik.
  • Tag memiliki nama mkt_medium dan nilai berdasarkan nilai string kueri utm_medium . Nilai utm_medium diatur ke rentang nilai yang diketahui.
  • Tag memungkinkan permintaan dikategorikan berdasarkan jenis menengah pemasaran, yang dapat berguna saat menganalisis lalu lintas aplikasi web.

Catatan

Ikuti praktik terbaik metrik multi-dimensi saat memperkaya dengan tag kustom. Tag yang terlalu banyak atau memiliki rentang yang tidak terikat membuat banyak kombinasi tag, menghasilkan dimensi tinggi. Alat koleksi memiliki batasan dimensi yang didukung untuk penghitung dan dapat memfilter hasil untuk mencegah penggunaan memori yang berlebihan.

Menolak metrik HTTP pada titik akhir dan permintaan tertentu

Memilih keluar dari metrik perekaman bermanfaat untuk titik akhir yang sering dipanggil oleh sistem otomatis, seperti pemeriksaan kesehatan. Merekam metrik untuk permintaan ini umumnya tidak perlu. Telemetri yang tidak diinginkan menggunakan sumber daya untuk mengumpulkan dan menyimpan, dan dapat mendistorsi hasil yang ditampilkan di dasbor telemetri.

Anda bisa mengecualikan permintaan HTTP ke titik akhir dari metrik dengan menambahkan metadata, dengan atribut DisableHttpMetrics atau metode DisableHttpMetrics :

• Tambahkan atribut DisableHttpMetrics ke pengontrol API Web, SignalR hub, atau layanan gRPC.
• Panggil DisableHttpMetrics saat memetakan titik akhir di startup aplikasi:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHealthChecks();

var app = builder.Build();
app.MapHealthChecks("/healthz").DisableHttpMetrics();
app.Run();

Sebagai alternatif, properti IHttpMetricsTagsFeature.MetricsDisabled ditambahkan untuk:

• Skenario lanjutan di mana permintaan tidak sesuai dengan titik akhir.
• Menonaktifkan pengumpulan metrik secara dinamis untuk permintaan HTTP tertentu.

// Middleware that conditionally opts-out HTTP requests.
app.Use(async (context, next) =>
{
    var metricsFeature = context.Features.Get<IHttpMetricsTagsFeature>();
    if (metricsFeature != null &&
        context.Request.Headers.ContainsKey("x-disable-metrics"))
    {
        metricsFeature.MetricsDisabled = true;
    }

    await next(context);
});

Membuat metrik kustom

Anda membuat metrik menggunakan API di namespace System.Diagnostics.Metrics. Untuk informasi, lihat Membuat metrik kustom.

Membuat metrik di aplikasi ASP.NET Core dengan IMeterFactory

Membuat instance Meter di aplikasi ASP.NET Core dengan IMeterFactory.

ASP.NET Core mendaftarkan IMeterFactory ke dalam injeksi dependensi (DI) secara default. Pabrik meteran mengintegrasikan metrik dengan DI, memudahkan isolasi dan pengumpulan metrik. IMeterFactory sangat berguna untuk pengujian. Ini memungkinkan beberapa pengujian berjalan berdampingan dan hanya mengumpulkan nilai metrik yang direkam dalam pengujian.

Untuk digunakan IMeterFactory dalam aplikasi, buat jenis yang menggunakan IMeterFactory untuk membuat metrik kustom aplikasi:

public class ContosoMetrics
{
    private readonly Counter<int> _productSoldCounter;

    public ContosoMetrics(IMeterFactory meterFactory)
    {
        var meter = meterFactory.Create("Contoso.Web");
        _productSoldCounter = meter.CreateCounter<int>("contoso.product.sold");
    }

    public void ProductSold(string productName, int quantity)
    {
        _productSoldCounter.Add(quantity,
            new KeyValuePair<string, object?>("contoso.product.name", productName));
    }
}

Daftarkan jenis metrik dengan DI di Program.cs:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<ContosoMetrics>();

Masukkan jenis metrik dan nilai rekaman jika diperlukan. Karena jenis metrik terdaftar di DI, jenis metrik dapat digunakan dengan pengontrol MVC, API Minimal, atau jenis lain yang dibuat oleh DI:

app.MapPost("/complete-sale", (SaleModel model, ContosoMetrics metrics) =>
{
    // ... business logic such as saving the sale to a database ...

    metrics.ProductSold(model.ProductName, model.QuantitySold);
});

Untuk memantau meteran "Contoso.Web", gunakan perintah penghitung dotnet berikut.

dotnet-counters monitor -n WebMetric --counters Contoso.Web

Output yang mirip dengan berikut ini ditampilkan:

Press p to pause, r to resume, q to quit.
    Status: Running

[Contoso.Web]
    contoso.product.sold (Count / 1 sec)
        contoso.product.name=Eggs            12    
        contoso.product.name=Milk            0    

Melihat metrik di Grafana dengan OpenTelemetry dan Prometheus

Overview

OpenTelemetry:

• Adalah proyek sumber terbuka vendor netral yang didukung oleh Cloud Native Computing Foundation.
• Menstandarkan pembuatan dan pengumpulan telemetri untuk perangkat lunak cloud-native.
• Bekerja dengan .NET menggunakan API metrik .NET.
• Didukung oleh Azure Monitor dan banyak vendor APM.

Tutorial ini menunjukkan salah satu integrasi yang tersedia untuk metrik OpenTelemetry menggunakan proyek OSS Prometheus dan Grafana . Data aliran metrik:

1. API metrik ASP.NET Core merekam pengukuran dari aplikasi contoh.

2. Pustaka OpenTelemetry .NET yang berjalan di aplikasi mengagregasi pengukuran.

3. Pustaka pengekspor Prometheus membuat data agregat tersedia melalui titik akhir metrik HTTP. Pengekspor adalah istilah yang digunakan oleh OpenTelemetry untuk pustaka yang mengirimkan telemetri ke backend khusus vendor.

4. Sebuah server Prometheus

   • Melakukan polling pada endpoint metrik.
   • Membaca data.
   • Menyimpan data dalam database untuk persistensi jangka panjang. Prometheus mengacu pada membaca dan menyimpan data sebagai mengikis titik akhir.
   • Dapat berjalan pada komputer yang berbeda.

5. Server Grafana:

   • Mengkueri data yang disimpan di Prometheus dan menampilkannya di dasbor pemantauan berbasis web.
   • Dapat berjalan pada komputer yang berbeda.

Menampilkan metrik dari aplikasi sampel

Buka aplikasi sampel. Browser menunjukkan Hello OpenTelemetry! ticks:<3digits> di mana 3digits adalah tiga digit terakhir dari DateTime.Ticks saat ini.

Tambahkan /metrics ke URL untuk melihat titik akhir metrik. Browser menampilkan metrik yang dikumpulkan:

Menyiapkan dan mengonfigurasi Prometheus

Ikuti langkah-langkah pertama Prometheus untuk menyiapkan server Prometheus dan mengonfirmasi bahwa prometheus berfungsi.

Ubah file konfigurasi prometheus.yml sehingga Prometheus mengikis titik akhir metrik yang diekspos aplikasi contoh. Tambahkan teks yang disorot berikut ini di bagian scrape_configs :

# my global config
global:
  scrape_interval: 15s # Set the scrape interval to every 15 seconds. Default is every 1 minute.
  evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute.
  # scrape_timeout is set to the global default (10s).

# Alertmanager configuration
alerting:
  alertmanagers:
    - static_configs:
        - targets:
          # - alertmanager:9093

# Load rules once and periodically evaluate them according to the global 'evaluation_interval'.
rule_files:
  # - "first_rules.yml"
  # - "second_rules.yml"

# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
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'.

    static_configs:
      - targets: ["localhost:9090"]

  - job_name: 'MyASPNETApp'
    scrape_interval: 5s # Poll every 5 seconds for a more responsive demo.
    static_configs:
      - targets: ["localhost:5045"]  ## Enter the HTTP port number of the demo app.

Di YAML yang disorot sebelumnya, ganti 5045 dengan nomor port yang digunakan aplikasi contoh.

Mulai Prometheus

1. Muat ulang konfigurasi atau mulai ulang server Prometheus.
2. Konfirmasikan bahwa OpenTelemetryTest berada dalam status UP di halaman Target Status>portal web Prometheus.

Pilih ikon Buka penjelajah metrik untuk melihat metrik yang tersedia:

Masukkan kategori penghitung seperti http_ dalam kotak Input ekspresi untuk melihat metrik yang tersedia:

Atau, masukkan kategori penghitung seperti kestrel di kotak Input ekspresi untuk melihat metrik yang tersedia:

Tampilkan metrik pada dasbor Grafana

• Ikuti instruksi penginstalan untuk menginstal Grafana dan menyambungkannya ke sumber data Prometheus.

• Ikuti Membuat grafik Prometheus. Atau, dasbor bawaan untuk metrik .NET tersedia untuk diunduh di dasbor tim .NET @ grafana.com. JSON dasbor yang diunduh dapat diimpor ke Grafana.

Menguji metrik di aplikasi ASP.NET Core

Anda dapat menguji metrik di aplikasi ASP.NET Core. Salah satu cara untuk melakukan ini adalah dengan mengumpulkan dan menegaskan nilai metrik dalam pengujian integrasi ASP.NET Core dengan menggunakan MetricCollector<T>.

public class BasicTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly WebApplicationFactory<Program> _factory;
    public BasicTests(WebApplicationFactory<Program> factory) => _factory = factory;

    [Fact]
    public async Task Get_RequestCounterIncreased()
    {
        // Arrange
        var client = _factory.CreateClient();
        var meterFactory = _factory.Services.GetRequiredService<IMeterFactory>();
        var collector = new MetricCollector<double>(meterFactory,
            "Microsoft.AspNetCore.Hosting", "http.server.request.duration");

        // Act
        var response = await client.GetAsync("/");

        // Assert
        Assert.Contains("Hello OpenTelemetry!", await response.Content.ReadAsStringAsync());

        await collector.WaitForMeasurementsAsync(minCount: 1).WaitAsync(TimeSpan.FromSeconds(5));
        Assert.Collection(collector.GetMeasurementSnapshot(),
            measurement =>
            {
                Assert.Equal("http", measurement.Tags["url.scheme"]);
                Assert.Equal("GET", measurement.Tags["http.request.method"]);
                Assert.Equal("/", measurement.Tags["http.route"]);
            });
    }
}

Tes sebelumnya:

• Bootstrap aplikasi web dalam memori dengan WebApplicationFactory<TEntryPoint>. Program dalam argumen generik pabrik menentukan aplikasi web.
• Mengumpulkan nilai metrik dengan MetricCollector<T>
  • Memerlukan referensi paket ke Microsoft.Extensions.Diagnostics.Testing.
  • MetricCollector<T> dibuat menggunakan IMeterFactory aplikasi web. Ini memungkinkan kolektor untuk hanya melaporkan nilai metrik yang direkam oleh pengujian.
  • Termasuk nama meter, Microsoft.AspNetCore.Hosting, dan nama penghitung, http.server.request.duration untuk pengumpulan.
• Membuat permintaan HTTP ke aplikasi web.
• Memverifikasi pengujian menggunakan hasil dari kolektor metrik.

metrik ASP.NET Core Identity

Identity ASP.NET Core observabilitas membantu Anda memantau aktivitas manajemen pengguna dan proses autentikasi.

Metrik berada dalam meteran Microsoft.AspNetCore.Identity dan dijelaskan di bagian berikut.

Metrik manajemen pengguna

• aspnetcore.identity.user.create.duration mengukur durasi proses pembuatan akun pengguna.
• aspnetcore.identity.user.update.duration mengukur durasi operasi pembaruan pengguna.
• aspnetcore.identity.user.delete.duration mengukur durasi operasi penghapusan pengguna.
• aspnetcore.identity.user.check_password_attempts menghitung upaya verifikasi kata sandi.
• aspnetcore.identity.user.generated_tokens menghitung token yang dihasilkan untuk pengguna, seperti token reset kata sandi.
• aspnetcore.identity.user.verify_token_attempts menghitung upaya verifikasi token.

Metrik autentikasi

• aspnetcore.identity.sign_in.authenticate.duration mengukur durasi operasi autentikasi.
• aspnetcore.identity.sign_in.check_password_attempts menghitung percobaan pengecekan kata sandi selama masuk.
• aspnetcore.identity.sign_in.sign_ins menghitung login yang berhasil.
• aspnetcore.identity.sign_in.sign_outs menghitung keluar akun.
• aspnetcore.identity.sign_in.two_factor_clients_remembered menghitung klien dua faktor yang diingat.
• aspnetcore.identity.sign_in.two_factor_clients_forgotten menghitung klien dua faktor yang terlupakan.

Gunakan metrik ini untuk:

• Pantau pendaftaran dan manajemen pengguna.
• Lacak pola autentikasi dan potensi masalah keamanan.
• Mengukur kinerja operasi Identity.
• Amati penggunaan autentikasi dua faktor.

Menampilkan Identity metrik

Gunakan dotnet-counters untuk melihat metrik ini dan memantaunya secara real time. Atau, ekspor ke Prometheus dan visualisasikan di Grafana dengan menggunakan teknik yang dijelaskan sebelumnya dalam artikel ini.

Misalnya, untuk memantau semua Identity metrik dengan dotnet-counters:

dotnet-counters monitor -n YourAppName --counters Microsoft.AspNetCore.Identity

pengukur dan penghitung inti ASP.NET

Untuk daftar pengukur dan penghitung ASP.NET Core, lihat metrik ASP.NET Core. Dalam ASP.NET Core 11 dan yang lebih baru, meter server HTTP bawaan (misalnya, Microsoft.AspNetCore.Hosting dan Microsoft.AspNetCore.Server.Kestrel) memancarkan data yang sesuai dengan bagian yang diperlukan dari konvensi semantik server HTTP OpenTelemetry. Anda dapat menggunakan meter ini dengan OpenTelemetry SDK tanpa paket OpenTelemetry.Instrumentation.AspNetCore.