ASP.NET Основные метрики

Метрики — это числовые измерения, сообщаемые с течением времени. Используйте их для мониторинга работоспособности приложения и создания оповещений. Например, веб-служба может отслеживать, сколько:

• Запросы, которые он получает в секунду.
• Миллисекунд, необходимых для ответа.
• Ответы, которые он отправляет с ошибкой.

Сообщите эти метрики системе мониторинга через регулярные интервалы. Настройте панели мониторинга для просмотра метрик и создания оповещений для уведомления людей о проблемах. Если веб-служба предназначена для реагирования на запросы в течение 400 мс и начинает отвечать в 600 мс, система мониторинга может уведомить сотрудников об операциях, что ответ приложения медленнее, чем обычно.

Полный список всех инструментов вместе с их атрибутами описан в ASP.NET Core встроенных метрик.

Используйте метрики

Использование метрик включает в себя следующее:

• Инструментирование: код в библиотеках .NET принимает измерения и связывает их с именем метрики. .NET и ASP.NET Core включают множество встроенных метрик.
• Коллекция и хранилище: Приложение .NET настраивает именованные метрики, передаваемые из приложения для внешнего хранилища и анализа. Некоторые средства могут выполнять конфигурацию за пределами приложения с помощью файлов конфигурации или средства пользовательского интерфейса.
• Визуализация: Средство, которое может отображать метрики в формате, доступном для чтения. Например, Aspire панель мониторинга, Grafana и Prometheus.
• Оповещения: Средство, которое предоставляет уведомления, когда метрика превышает пороговое значение. Например, если среднее время отклика для веб-службы превышает 400 мс, можно отправить оповещение сотрудникам по операциям.
• Анализ: Средство, которое может анализировать метрики с течением времени. Это средство часто представляет собой веб-панель мониторинга, которую можно настроить для отображения наиболее важных метрик для конкретного приложения.

Инструментированный код может записывать числовые измерения, но для создания полезных метрик для мониторинга необходимо агрегировать, передавать и хранить измерения. Процесс агрегирования, передачи и хранения данных называется коллекцией. В этом руководстве показано несколько примеров сбора и отображения метрик:

• Заполнение метрик в Grafana с помощью OpenTelemetry и Prometheus.
• Просмотр метрик в реальном времени с dotnet-counters.

Другие варианты визуализации см. в обзореAspire панели мониторинга.

Можно также связать измерения с парами "ключ-значение", называемыми тегами, которые позволяют классифицировать данные для анализа. Дополнительные сведения см. в разделе "Многомерные метрики".

Создание начального приложения

Создайте новое приложение ASP.NET Core с помощью следующей команды:

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

Замените все содержимое Program.cs следующим кодом:

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();

Просмотр метрик с помощью dotnet-counters

dotnet-counters — это средство командной строки, которое может просматривать динамические метрики для приложений .NET по запросу. Для этого не требуется настройка, что полезно для экстренных расследований или проверки работы метрических инструментов. Она работает с API-интерфейсами на основе System.Diagnostics.Metrics и счетчиками событий.

Если средство dotnet-counters не установлено, выполните следующую команду:

dotnet tool update -g dotnet-counters

Во время работы тестового приложения запустите dotnet-counters. В следующей команде показан пример dotnet-counters мониторинга всех метрик из счетчикаMicrosoft.AspNetCore.Hosting.

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

Выходные данные должны выглядеть примерно так:

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

Дополнительные сведения см. в разделе dotnet-counters.

Обогащение метрики запроса ASP.NET Core

ASP.NET Core имеет множество встроенных метрик. Метрика http.server.request.duration

• Записывает длительность HTTP-запросов на сервере.
• Записывает сведения о запросах в тегах, таких как соответствующий маршрут и код состояния ответа.

http.server.request.duration Метрика поддерживает обогащение тегов с помощью IHttpMetricsTagsFeature. Обогащение заключается в том, что библиотека или приложение добавляет собственные теги в метрику. Эта функция полезна, если приложение хочет добавить настраиваемую категорию на панели мониторинга или оповещения, созданные с помощью метрик.

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();

Предшествующий пример:

• Добавляет промежуточное ПО для обогащения метрики запроса ASP.NET Core.
• Извлекает IHttpMetricsTagsFeature из HttpContext. Функция присутствует в контексте только в том случае, если пользователь прослушивает метрику. Убедитесь, что IHttpMetricsTagsFeature не null, прежде чем использовать его.
• Добавляет пользовательский тег, содержащий источник маркетинга запроса, в метрику http.server.request.duration .
  • Тег имеет имя mkt_medium, а его значение основано на значении строки запроса utm_medium. Значение utm_medium сводится к известному диапазону значений.
  • Тег позволяет классифицировать запросы по среднему типу маркетинга, что может быть полезно при анализе трафика веб-приложения.

Примечание.

Следуйте лучшим практикам многомерных метрик при обогащении с помощью пользовательских тегов. Теги, которые слишком многочисленны или имеют неопределённый диапазон, создают множество сочетаний тегов, что приводит к высокой размерности. Средства сбора имеют ограничения на поддерживаемые измерения счетчика и могут фильтровать результаты, чтобы предотвратить чрезмерное использование памяти.

Отказ от метрики HTTP в определенных конечных точках и запросах

Отказ от сбора метрик полезен для конечных точек, которые часто используются автоматизированными системами, например, для проверок состояния. Регистрация метрик для этих запросов, как правило, не нужна. Нежелательные данные телеметрии используют ресурсы для сбора и хранения и могут исказить результаты, отображаемые на панели мониторинга телеметрии.

Http-запросы к конечной точке можно исключить из метрик, добавив метаданные с помощью атрибута DisableHttpMetrics или метода DisableHttpMetrics:

• Добавьте атрибут DisableHttpMetrics в контроллер веб-API, SignalR концентратор или службу gRPC.
• Вызов DisableHttpMetrics при сопоставлении конечных точек при запуске приложения:

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

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

Кроме того, IHttpMetricsTagsFeature.MetricsDisabled свойство было добавлено для:

• Расширенные сценарии, в которых запрос не сопоставляется с конечной точкой.
• Динамическое отключение сбора метрик для определенных HTTP-запросов.

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

Создание пользовательских метрик

Вы создаете метрики с помощью API в пространстве имен System.Diagnostics.Metrics. Дополнительные сведения см. в разделе "Создание пользовательских метрик".

Создание метрик в приложениях ASP.NET Core с помощью IMeterFactory

Создавайте экземпляры Meter в приложениях ASP.NET Core с помощью IMeterFactory.

ASP.NET Core по умолчанию регистрирует IMeterFactory в контейнере внедрения зависимостей (DI). Фабрика счетчиков интегрирует метрики с DI, что упрощает изоляцию и сбор метрик. IMeterFactory особенно полезно для тестирования. Он позволяет выполнять несколько тестов параллельно и собирать только значения метрик, записанные в тесте.

Чтобы использовать IMeterFactory в приложении, создайте тип, использующий IMeterFactory для создания пользовательских метрик приложения.

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));
    }
}

Зарегистрируйте тип метрик с помощью DI в Program.cs:

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

Введите тип метрик и значения записей, если это необходимо. Так как тип метрик зарегистрирован в DI, его можно использовать с контроллерами MVC, минимальными API или любым другим типом, созданным 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);
});

Чтобы отслеживать счетчик contoso.Web, используйте следующую команду dotnet-counters .

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

Выходные данные должны выглядеть примерно так:

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    

Просмотр метрик в Grafana с помощью OpenTelemetry и Prometheus.

Overview

OpenTelemetry:

• Является независимым от поставщиков проектом с открытым исходным кодом, поддерживаемым Cloud Native Computing Foundation.
• Стандартизирует создание и сбор данных телеметрии для облачного программного обеспечения.
• Работает с .NET с помощью API метрик .NET.
• Поддерживается Azure Monitor и многими поставщиками APM.

В этом руководстве показана одна из интеграции, доступная для метрик OpenTelemetry с помощью проектов OSS Prometheus и Grafana . Поток данных метрик:

1. ASP.NET API основных метрик записывают измерения из примера приложения.

2. Библиотека OpenTelemetry .NET, запущенная в приложении, агрегирует измерения.

3. Библиотека программы экспорта Prometheus предоставляет доступ к агрегированным данным через конечную точку метрик HTTP. «Экспортер» — это то, как OpenTelemetry называет библиотеки, которые передают телеметрию в серверы конкретных поставщиков.

4. Сервер Prometheus:

   • Опрашивает конечную точку метрик.
   • Считывает данные.
   • Сохраняет данные в базе данных для долгосрочного сохранения. Prometheus относится к чтению и хранению данных как к извлечению данных с конечной точки.
   • Может работать на другом компьютере.

5. Сервер Grafana:

   • Запрашивает данные, хранящиеся в Prometheus, и отображает его на веб-панели мониторинга.
   • Может работать на другом компьютере.

Просмотр метрик из примера приложения

Перейдите к примеру приложения. В браузере отображается Hello OpenTelemetry! ticks:<3digits>, где 3digits — это последние три цифры текущего значения DateTime.Ticks.

Добавьте /metrics к URL-адресу для просмотра конечной точки метрик. В браузере отображаются собираемые метрики:

Установка и настройка Prometheus

Выполните первые действия Prometheus, чтобы настроить сервер Prometheus и подтвердить его работу.

Измените файл конфигурации prometheus.yml, чтобы Prometheus собирал метрики с конечной точки, которую предоставляет пример приложения. Добавьте следующий выделенный текст в 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.

В приведённом выше выделенном фрагменте YAML замените 5045 на номер порта, который использует пример приложения.

Запуск Prometheus

1. Перезагрузите конфигурацию или перезапустите сервер Prometheus.
2. Убедитесь, что OpenTelemetryTest находится в состоянии UP на странице Состояние>Цели веб-портала Prometheus.

Щелкните значок "Открыть обозреватель метрик", чтобы просмотреть доступные метрики.

Введите категорию счётчика, например http_, в поле ввода Expression, чтобы увидеть доступные метрики:

Кроме того, введите категорию счетчиков, например kestrel в поле ввода выражения , чтобы просмотреть доступные метрики:

Отображение метрик на панели мониторинга Grafana

• Следуйте инструкциям по установке Grafana и подключите его к источнику данных Prometheus.

• Следуйте инструкциям по созданию графа Prometheus. Кроме того, предварительно созданные панели мониторинга для метрик .NET доступны для скачивания на панелях мониторинга команд .NET @ grafana.com. Скачанный JSON панели мониторинга можно импортировать в Grafana.

Тестирование метрик в приложениях ASP.NET Core

Метрики можно протестировать в приложениях ASP.NET Core. Одним из способов этого является сбор и утверждение значений метрик в ASP.NET Core тестах интеграции с помощью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"]);
            });
    }
}

Предыдущий тест:

• Загружает в память веб-приложение с помощью WebApplicationFactory<TEntryPoint>. Program В универсальном аргументе фабрики указывается веб-приложение.
• Собирает значения метрик с помощью MetricCollector<T>
  • Требуется ссылка на Microsoft.Extensions.Diagnostics.Testingпакет.
  • Веб-приложение MetricCollector<T> используется для создания IMeterFactory. Это позволяет сборщику сообщать только значения метрик, записанные тестом.
  • Включает имя прибора Microsoft.AspNetCore.Hosting, и имя счетчика http.server.request.duration для сбора.
• Выполняет HTTP-запрос к веб-приложению.
• Утверждает тест с помощью результатов сборщика метрик.

Метрики ASP.NET Core Identity

ASP.NET Core Identity помогает отслеживать операции по управлению пользователями и процессы аутентификации.

Метрики находятся в Microsoft.AspNetCore.Identity счетчике и описаны в следующих разделах.

Метрики управления пользователями

• aspnetcore.identity.user.create.duration измеряет длительность операций по созданию пользователей.
• aspnetcore.identity.user.update.duration измеряет продолжительность операций обновления данных пользователей.
• aspnetcore.identity.user.delete.duration измеряет длительность операций удаления пользователей.
• aspnetcore.identity.user.check_password_attempts подсчитывает попытки проверки пароля.
• aspnetcore.identity.user.generated_tokens подсчитывает токены, созданные для пользователей, такие как токены для сброса пароля.
• aspnetcore.identity.user.verify_token_attempts подсчитывает попытки проверки токена.

Метрики проверки подлинности

• aspnetcore.identity.sign_in.authenticate.duration измеряет длительность операций проверки подлинности.
• aspnetcore.identity.sign_in.check_password_attempts подсчитывает попытки проверки пароля во время входа.
• aspnetcore.identity.sign_in.sign_ins подсчитывает успешные входы.
• aspnetcore.identity.sign_in.sign_outs подсчитывает выходы из системы.
• aspnetcore.identity.sign_in.two_factor_clients_remembered ведет учет сохраненных двухфакторных клиентов.
• aspnetcore.identity.sign_in.two_factor_clients_forgotten учитывает забытых клиентов двухфакторной аутентификации.

Используйте следующие метрики для:

• Мониторинг регистрации и управления пользователями.
• Отслеживайте шаблоны проверки подлинности и потенциальные проблемы безопасности.
• Измеряйте производительность операций Identity.
• Обратите внимание на использование двухфакторной проверки подлинности.

Просмотр Identity метрик

Используется dotnet-counters для просмотра этих метрик и отслеживания их в режиме реального времени. Или экспортируйте их в Prometheus и визуализируйте их в Grafana, используя методы, описанные ранее в этой статье.

Например, чтобы отслеживать все Identity метрики с помощью dotnet-counters:

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

ASP.NET Core метрические показатели и счетчики

Список измерителей и счетчиков ASP.NET Core см. в разделе Метрики ASP.NET Core. В ASP.NET Core 11 и более поздних версий встроенные счетчики HTTP-сервера (например, Microsoft.AspNetCore.Hosting иMicrosoft.AspNetCore.Server.Kestrel) выдают данные, соответствующие необходимым частям семантических соглашений HTTP-сервера OpenTelemetry. Эти счётчики можно использовать с OpenTelemetry SDK без пакета OpenTelemetry.Instrumentation.AspNetCore.

Дополнительные ресурсы

• Aspire Обзор панели мониторинга
• Изучите Aspire телеметрию
• встроенные метрики ASP.NET Core