Síťové metriky v .NET

Metriky jsou číselná měření hlášená v průběhu času. Obvykle se používají ke sledování stavu aplikace a generování výstrah.

Počínaje rozhraním .NET 8 jsou komponenty System.Net.Http a System.Net.NameResolution instrumentovány pro publikování metrik pomocí nového rozhraní API System.Diagnostics.Metrics .NET. Tyto metriky byly navrženy ve spolupráci s OpenTelemetry, aby byly konzistentní se standardem a dobře fungovaly s oblíbenými nástroji, jako jsou Prometheus a Grafana. Jsou také multidimenzionální, což znamená, že měření jsou přidružená ke párům klíč-hodnota označovaným také jako značky (označované také jako atributy nebo popisky). Značky umožňují kategorizaci měření, která pomáhá analyzovat.

Spropitné

Pro úplný seznam všech vestavěných nástrojů a jejich atributů se podívejte na metriky systému System.Net.

Shromažďování metrik System.Net

Aby bylo možné využít integrované instrumentace metrik, musí být aplikace .NET nakonfigurovaná tak, aby tyto metriky shromažďovala. To obvykle znamená jejich transformaci pro externí úložiště a analýzu, například na systémy monitorování.

Existuje několik způsobů, jak shromažďovat síťové metriky v .NET.

Rychlý přehled pomocí jednoduchého samostatného příkladu najdete v tématu Shromažďování metrik pomocí čítačů dotnet.
Pro shromažďování a monitorování metrik v produkčním prostředí můžete použít Grafana s OpenTelemetry a Prometheus nebo Azure Monitor Application Insights. Tyto nástroje ale můžou být kvůli složitosti nevhodné k použití v době vývoje.
Pro shromažďování metrik v době vývoje a řešení potíží doporučujeme použít Aspire, což poskytuje jednoduchý, ale rozšiřitelný způsob, jak začít s metrikami a distribuované trasování ve vaší aplikaci a diagnostikovat problémy místně.
Je také možné použití výchozích hodnot služby Aspire bez orchestrace Aspire, což je užitečný způsob, jak do projektu ASP.NET zavést rozhraní API pro trasování OpenTelemetry a konfiguraci metrik.

Shromažďování metrik pomocí čítačů dotnet

dotnet-counters je multiplatformní nástroj příkazového řádku pro ad hoc zkoumání metrik .NET a šetření výkonu na první úrovni.

Pro účely tohoto kurzu vytvořte aplikaci, která paralelně odesílá požadavky HTTP na různé koncové body.

dotnet new console -o HelloBuiltinMetrics
cd ..\HelloBuiltinMetrics

Nahraďte obsah Program.cs následujícím vzorovým kódem:

using System.Net;

string[] uris = ["http://example.com", "http://httpbin.org/get", "https://example.com", "https://httpbin.org/get"];
using HttpClient client = new()
{
    DefaultRequestVersion = HttpVersion.Version20
};

Console.WriteLine("Press any key to start.");
Console.ReadKey();

while (!Console.KeyAvailable)
{
    await Parallel.ForAsync(0, Random.Shared.Next(20), async (_, ct) =>
    {
        string uri = uris[Random.Shared.Next(uris.Length)];
        try
        {
            byte[] bytes = await client.GetByteArrayAsync(uri, ct);
            await Console.Out.WriteLineAsync($"{uri} - received {bytes.Length} bytes.");
        }
        catch { await Console.Out.WriteLineAsync($"{uri} - failed."); }
    });
}

Ujistěte se, že je nainstalovaný dotnet-counters:

dotnet tool install --global dotnet-counters

Spusťte aplikaci HelloBuiltinMetrics.

dotnet run -c Release

Spusťte dotnet-counters v samostatném okně rozhraní příkazového řádku a zadejte název procesu a měřiče, které chcete sledovat, a pak stiskněte klávesu v aplikaci HelloBuiltinMetrics, aby začal odesílat požadavky. Jakmile se měření spustí, dotnet-counters konzolu průběžně aktualizuje nejnovějšími čísly:

dotnet-counters monitor --counters System.Net.Http,System.Net.NameResolution -n HelloBuiltinMetrics

výstup nástroje dotnet-counters

Shromažďování metrik pomocí Aspire

Jednoduchý způsob, jak shromažďovat trasování a metriky v ASP.NET aplikacích, je použít Aspire. Aspire je sada rozšíření, která .NET usnadňují vytváření a práci s distribuovanými aplikacemi. Jednou z výhod používání Aspire je, že telemetrie je integrovaná pomocí knihoven OpenTelemetry pro .NET.

Výchozí šablony projektů pro Aspire projekt obsahují ServiceDefaults projekt. Každá služba v Aspire řešení má odkaz na projekt Výchozí služby. Služby ji používají k nastavení a konfiguraci OTelu.

Šablona projektu Výchozí nastavení služby zahrnuje balíčky OTel SDK, ASP.NET, HttpClient a Runtime Instrumentation. Tyto komponenty instrumentace jsou nakonfigurovány v souboru Extensions.cs. Pro podporu vizualizace telemetrie na Aspire řídicím panelu zahrnuje projekt Výchozí nastavení služby ve výchozím nastavení také exportér OTLP.

Aspire Řídicí panel je navržený tak, aby integroval sledování telemetrie do místního cyklu ladění, což vývojářům umožňuje ověřit, že aplikace generují telemetrii. Vizualizace telemetrie také pomáhá diagnostikovat tyto aplikace místně. Schopnost sledovat volání mezi službami je stejně užitečná v době ladění jako v produkčním prostředí. Nástěnka Aspire se spustí automaticky, když F5 projekt z AppHost Visual Studio nebo dotnet run projekt z AppHost příkazového řádku.

Rychlý návod

Vytvořte úvodníAspire aplikaci 9 pomocídotnet new:
```
dotnet new aspire-starter-9 --output AspireDemo
```
Nebo v Visual Studio vytvořte nový projekt a vyberte šablonu Aspire 9 Starter App:

Otevřete Extensions.cs v projektu ServiceDefaults a posuňte se k metodě ConfigureOpenTelemetry. Všimněte si volání AddHttpClientInstrumentation(), které se přihlašuje k síťovým měřičům.

.WithMetrics(metrics =>
{
    metrics.AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddRuntimeInstrumentation();
})

Všimněte si, že v rozhraní .NET 8 nebo novějších je možné AddHttpClientInstrumentation() nahradit ručními předplatnými měřičů:

.WithMetrics(metrics =>
{
    metrics.AddAspNetCoreInstrumentation()
        .AddMeter("System.Net.Http")
        .AddMeter("System.Net.NameResolution")
        .AddRuntimeInstrumentation();
})

Spusťte projekt AppHost. Tím by se měl spustit Aspire řídicí panel.
Přejděte na stránku Počasí aplikace webfrontend a vygenerujte HttpClient žádost o apiservice. Aktualizujte stránku několikrát, aby se odeslalo více požadavků.
Vraťte se na řídicí panel, přejděte na stránku Metriky a vyberte prostředek webfrontend. Posouváním dolů byste měli být schopni procházet předdefinované metriky System.Net.

Pro více informací o Aspire viz:

Opětovné použití projektu Výchozí hodnoty služby bez Aspire orchestrace

Projekt výchozích nastavení služby Aspire poskytuje snadný způsob konfigurace OTelu pro projekty ASP.NET, i když nevyužíváte zbytek Aspire, jako je například AppHost pro orchestraci. Projekt Výchozí nastavení služby je k dispozici jako šablona projektu prostřednictvím sady Visual Studio nebo dotnet new. Nakonfiguruje OTel a nastaví exportér OTLP. Pak můžete použít proměnné prostředí OTel k nastavení koncového bodu OTLP pro odesílání telemetrie a k nastavení vlastností prostředků aplikace.

Postup použití ServiceDefaults mimo Aspire následující:

Přidejte do řešení projekt ServiceDefaults pomocí příkazu Přidat nový projekt v sadě Visual Studio nebo použijte dotnet new:
```
dotnet new aspire-servicedefaults --output ServiceDefaults
```
Odkazujte na projekt ServiceDefaults z aplikace ASP.NET. V sadě Visual Studio vyberte Přidat>odkaz projektu a vyberte projekt ServiceDefaults

Jako součást inicializace tvůrce aplikací volejte funkci nastavení OpenTelemetry ConfigureOpenTelemetry().

var builder = WebApplication.CreateBuilder(args)
builder.ConfigureOpenTelemetry(); // Extension method from ServiceDefaults.
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.Run();

Úplný návod najdete v tématu Příklad: Použití OpenTelemetry s OTLP a samostatným Aspire řídicím panelem.

Zobrazení metrik v Grafaně pomocí OpenTelemetry a Prometheus

Pokud chcete zjistit, jak připojit ukázkovou aplikaci s aplikací Prometheus a Grafana, postupujte podle návodu v Použití OpenTelemetry s aplikací Prometheus, Grafana a Jaeger.

Pokud chcete zdůraznit HttpClient odesláním paralelních požadavků do různých koncových bodů, rozšiřte ukázkovou aplikaci o následující koncový bod:

app.MapGet("/ClientStress", async Task<string> (ILogger<Program> logger, HttpClient client) =>
{
    string[] uris = ["http://example.com", "http://httpbin.org/get", "https://example.com", "https://httpbin.org/get"];
    await Parallel.ForAsync(0, 50, async (_, ct) =>
    {
        string uri = uris[Random.Shared.Next(uris.Length)];

        try
        {
            await client.GetAsync(uri, ct);
            logger.LogInformation($"{uri} - done.");
        }
        catch { logger.LogInformation($"{uri} - failed."); }
    });
    return "Sent 50 requests to example.com and httpbin.org.";
});

Výběrem ikony + na horním panelu nástrojů a následným výběrem řídicího paneluvytvořte řídicí panel Grafana. V zobrazeném editoru řídicího panelu zadejte Otevřít připojení HTTP/1.1 do pole Název a do pole výrazu PromQL zadejte následující dotaz:

sum by(http_connection_state) (http_client_open_connections{network_protocol_version="1.1"})

Vyberte Použít pro uložení a zobrazení nového řídicího panelu. Zobrazí počet aktivních a nečinných připojení HTTP/1.1 ve fondu.

Obohacení

Obohacení je přidání vlastních štítků (označovaných také jako atributy nebo popisky) k metrice. To je užitečné v případě, že aplikace chce přidat vlastní kategorizaci na řídicí panely nebo výstrahy vytvořené pomocí metrik. Nástroj http.client.request.duration podporuje obohacení registrací zpětných volání u HttpMetricsEnrichmentContext. Upozorňujeme, že se jedná o nízkoúrovňové API a pro každou HttpRequestMessageje nutná samostatná registrace zpětného volání.

Jednoduchým způsobem provedení registrace zpětného volání na jednom místě je implementace vlastního DelegatingHandler. To vám umožní zachytávat a upravovat požadavky před jejich předáním do vnitřního správce a odesláním na server.

using System.Net.Http.Metrics;

using HttpClient client = new(new EnrichmentHandler() { InnerHandler = new HttpClientHandler() });

await client.GetStringAsync("https://httpbin.org/response-headers?Enrichment-Value=A");
await client.GetStringAsync("https://httpbin.org/response-headers?Enrichment-Value=B");

sealed class EnrichmentHandler : DelegatingHandler
{
    protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        HttpMetricsEnrichmentContext.AddCallback(request, static context =>
        {
            if (context.Response is not null) // Response is null when an exception occurs.
            {
                // Use any information available on the request or the response to emit custom tags.
                string? value = context.Response.Headers.GetValues("Enrichment-Value").FirstOrDefault();
                if (value != null)
                {
                    context.AddCustomTag("enrichment_value", value);
                }
            }
        });
        return base.SendAsync(request, cancellationToken);
    }
}

Pokud pracujete s IHttpClientFactory, můžete AddHttpMessageHandler použít k registraci EnrichmentHandler:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using System.Net.Http.Metrics;

ServiceCollection services = new();
services.AddHttpClient(Options.DefaultName).AddHttpMessageHandler(() => new EnrichmentHandler());

ServiceProvider serviceProvider = services.BuildServiceProvider();
HttpClient client = serviceProvider.GetRequiredService<HttpClient>();

await client.GetStringAsync("https://httpbin.org/response-headers?Enrichment-Value=A");
await client.GetStringAsync("https://httpbin.org/response-headers?Enrichment-Value=B");

Poznámka

Z důvodů výkonu se zpětné volání pro obohacení vyvolá pouze v případě, že je povolen nástroj http.client.request.duration, což znamená, že by měly být shromažďovány metriky. Může to být dotnet-monitor, Prometheus Exporter, MeterListenernebo MetricCollector<T>.

integrace `IMeterFactory` a `IHttpClientFactory`

Metriky HTTP byly navrženy s ohledem na izolaci a testovatelnost. Tyto aspekty jsou podporovány použitím IMeterFactory, což umožňuje publikování metrik pomocí vlastní instance Meter, aby měřiče zůstaly izolované od sebe navzájem. Ve výchozím nastavení se k vysílání všech metrik používá globální Meter. Toto Meter je interní k knihovně System.Net.Http. Toto chování lze přepsat přiřazením vlastní instance IMeterFactory k SocketsHttpHandler.MeterFactory nebo HttpClientHandler.MeterFactory.

Poznámka

Meter.Name je System.Net.Http pro všechny metriky generované HttpClientHandler a SocketsHttpHandler.

Při práci s Microsoft.Extensions.Http a IHttpClientFactory v rozhraní .NET 8 nebo novějším se výchozí implementace IHttpClientFactory automaticky vybere instanci IMeterFactory zaregistrovanou v IServiceCollection a přiřadí ji primární obslužné rutině, která vytvoří interně.

Poznámka

Počínaje rozhraním .NET 8 metoda AddHttpClient automaticky volá AddMetrics k inicializaci služeb metrik a registraci výchozí implementace IMeterFactory pomocí IServiceCollection. Výchozí IMeterFactory ukládá Meter instance podle názvu, což znamená, že existuje jeden Meter s názvem System.Net.Http na IServiceCollection.

Testování metrik

Následující příklad ukazuje, jak ověřit integrované metriky v testech jednotek pomocí xUnit, IHttpClientFactorya MetricCollector<T> z balíčku NuGet Microsoft.Extensions.Diagnostics.Testing:

[Fact]
public async Task RequestDurationTest()
{
    // Arrange
    ServiceCollection services = new();
    services.AddHttpClient();
    ServiceProvider serviceProvider = services.BuildServiceProvider();
    var meterFactory = serviceProvider.GetService<IMeterFactory>();
    var collector = new MetricCollector<double>(meterFactory,
        "System.Net.Http", "http.client.request.duration");
    var client = serviceProvider.GetRequiredService<HttpClient>();

    // Act
    await client.GetStringAsync("http://example.com");

    // Assert
    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"]);
        });
}

Metriky vs. Počítadla událostí

Metriky jsou bohatší na funkce než EventCounters, zejména kvůli jejich multidimenzionální povaze. Tato multidimenzionální funkce umožňuje vytvářet sofistikované dotazy v nástrojích, jako je Prometheus, a získat přehledy na úrovni, která není možná u EventCounters.

V případě rozhraní .NET 8 se však instrumentují pouze System.Net.Http a komponenty System.Net.NameResolutions pomocí metrik, což znamená, že pokud potřebujete čítače z nižších úrovní zásobníku, jako je System.Net.Sockets nebo System.Net.Security, musíte použít EventCounters.

Kromě toho existují některé sémantické rozdíly mezi metrikami a jejich odpovídajícími hodnotami EventCounters. Například při použití HttpCompletionOption.ResponseContentReadcurrent-requests EventCounter považuje požadavek za aktivní až do okamžiku, kdy se přečte poslední bajt textu požadavku. Jeho protějšk metrik http.client.active_requests nezahrnuje čas strávený čtením textu odpovědi při počítání aktivních požadavků.

Potřebujete další metriky?

Pokud máte návrhy na další užitečné informace, které by mohly být zpřístupněny prostřednictvím metrik, vytvořte problém dotnet/runtime.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-04-27

Síťové metriky v .NET

Shromažďování metrik System.Net

Shromažďování metrik pomocí čítačů dotnet

Shromažďování metrik pomocí Aspire

Rychlý návod

Opětovné použití projektu Výchozí hodnoty služby bez Aspire orchestrace

Zobrazení metrik v Grafaně pomocí OpenTelemetry a Prometheus

Obohacení

integrace IMeterFactory a IHttpClientFactory

Testování metrik

Metriky vs. Počítadla událostí

Potřebujete další metriky?

Váš názor

Další materiály

integrace `IMeterFactory` a `IHttpClientFactory`