Пример. Использование OpenTelemetry с OTLP и автономной панелью мониторинга Aspire

Это один из ряда примеров для иллюстрации наблюдаемости .NET с помощью OpenTelemetry.

Помимо того, что является стандартной частью .NET Aspire, панель мониторинга Aspire доступна как автономный контейнер Docker, который предоставляет конечную точку OTLP, на которую можно отправлять телеметрию, а также визуализировать журналы, метрики и трассировки. Использование панели мониторинга таким образом не зависит от .NET Aspire, приборная панель будет визуализировать данные телеметрии из любого приложения, отправляющего данные телеметрии через OTLP. Он работает одинаково хорошо для приложений, написанных на Java, GoLang, Python и т. д. при условии, что они могут отправлять данные телеметрии в конечную точку OTLP.

Использование панели мониторинга Aspire имеет меньше настроек и действий по настройке, чем использование таких решений с открытым исходным кодом, как Prometheus, Grafana и Jaeger, но в отличие от этих средств, панель мониторинга Aspire предназначена в качестве средства визуализации разработчика, а не для производственного мониторинга.

1. Создание проекта

Создайте простой проект веб-API с помощью шаблона ASP.NET Core Empty в Visual Studio или следующей команды .NET CLI:

dotnet new web

2. Добавление метрик и определений действий

Следующий код определяет новую метрику (greetings.count) для количества вызовов API и нового источника действия (Otel.Example).

// Custom metrics for the application
var greeterMeter = new Meter("OTel.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("OTel.Example");

3. Создание конечной точки API

Вставка следующих элементов между builder.Build(); и app.Run()

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!";
}

4. Ссылка на пакеты OpenTelemetry

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

  <ItemGroup>
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" 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>

5. Настройте OpenTelemetry с помощью правильных поставщиков

Вставьте следующий код перед builder.Build();:

// Setup logging to be exported via OpenTelemetry
builder.Logging.AddOpenTelemetry(logging =>
{
    logging.IncludeFormattedMessage = true;
    logging.IncludeScopes = true;
});

var otel = builder.Services.AddOpenTelemetry();

// Add Metrics for ASP.NET Core and our custom metrics and export via OTLP
otel.WithMetrics(metrics =>
{
    // Metrics provider from OpenTelemetry
    metrics.AddAspNetCoreInstrumentation();
    //Our custom metrics
    metrics.AddMeter(greeterMeter.Name);
    // Metrics provides by ASP.NET Core in .NET 8
    metrics.AddMeter("Microsoft.AspNetCore.Hosting");
    metrics.AddMeter("Microsoft.AspNetCore.Server.Kestrel");
});

// Add Tracing for ASP.NET Core and our custom ActivitySource and export via OTLP
otel.WithTracing(tracing =>
{
    tracing.AddAspNetCoreInstrumentation();
    tracing.AddHttpClientInstrumentation();
    tracing.AddSource(greeterActivitySource.Name);
});

// Export OpenTelemetry data via OTLP, using env vars for the configuration
var OtlpEndpoint = builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"];
if (OtlpEndpoint != null)
{
    otel.UseOtlpExporter();
}

Этот код настраивает OpenTelemetry для различных источников телеметрии.

• Он добавляет поставщика OTel в ILogger для сбора логов.
• Он настраивает метрики, регистрируя поставщиков инструментирования и счетчики для ASP.NET и наш пользовательский счетчик.
• Он настраивает трассировку, регистрируя поставщиков инструментирования и наш пользовательский источник активности (ActivitySource).

Затем он регистрирует экспортер OTLP с помощью env vars для его конфигурации.

6. Настройка переменных среды OTLP

Экспортер OTLP можно настраивать через API в коде, но чаще его настраивают с помощью переменных среды. Добавьте следующее в AppSettings.Development.json

"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
"OTEL_SERVICE_NAME": "OTLP-Example"

Можно добавить дополнительные переменные среды для экспортера OTLP .NET или распространенных переменных OTel, например OTEL_RESOURCE_ATTRIBUTES для определения атрибутов ресурсов.

7. Запустите контейнер панели мониторинга Aspire

Используйте docker для скачивания и запуска контейнера панели мониторинга.

docker run --rm -it `
-p 18888:18888 `
-p 4317:18889 `
--name aspire-dashboard `
mcr.microsoft.com/dotnet/aspire-dashboard:latest

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

[]

Скопируйте отображаемый URL-адрес и замените 0.0.0.0 на localhost, например http://localhost:18888/login?t=123456780abcdef123456780, и откройте его в вашем браузере, или вы также можете вставить ключ после /login?t=, когда появится диалоговое окно входа. Маркер будет изменяться при каждом запуске контейнера.

8. Запуск проекта

Запустите проект и получите доступ к API с помощью браузера или curl.

curl -k http://localhost:7275

Каждый раз, когда вы запрашиваете страницу, он увеличивает количество приветствий, которые были сделаны.

Выходные данные журнала 8.1

Операторы ведения журнала из кода выводятся с использованием ILogger. По умолчанию поставщик консоли включён, чтобы выходные данные направлялись в консоль.

Пара вариантов экспортирования журналов из .NET:

• stdout и stderr перенаправляются контейнерными системами, такими как Kubernetes, в файлы журнала.
• Используя библиотеки ведения журнала, которые будут интегрироваться с ILogger, к ним относятся Serilog или NLog.
• Использование поставщиков ведения журналов для OTel, таких как OTLP. Раздел логирования в коде из шага 5 добавляет поставщика OTel.

Журналы отображаются на панели мониторинга как структурированные журналы. Все свойства, заданные в сообщении журнала, извлекаются в виде полей в записи журнала.

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

Панель мониторинга Aspire отображает метрики для каждого ресурса (ресурс в терминологии OTel обозначает источники телеметрии, такие как процесс). При выборе ресурса панель мониторинга перечисляет каждую метрику, отправленную в конечную точку OTLP ресурсом. Список метрик является динамическим и будет обновлен по мере получения новых метрик.

Представление метрик зависит от типа используемой метрики:

• Счетчики будут отображаться напрямую.
• Гистограммы, отслеживающие значение каждого запроса, такие как интервал времени или байты, отправленные на запрос, собираются в ряд сегментов. На дашборде будут отображаться процентили P50, P90 и P99. Результаты гистограммы могут включать образцы, которые являются отдельными точками данных вместе с trace или spanId для этого запроса. Они будут отображаться как точки на графе. При выборе одного из вариантов вы перейдете к соответствующему отслеживанию, чтобы увидеть, что послужило причиной этого значения. Это полезно для диагностики выбросов.
• Метрики могут включать измерения, которые являются парами "ключ-значение", связанными с отдельными значениями. Значения агрегируются по измерениям. С помощью раскрывающихся списков в представлении можно отфильтровать результаты, чтобы просматривать определенные параметры, такие как запросы только GET, или для конкретного URL-маршрута в ASP.NET.

8.3 Просмотр трассировки

В представлении трассировки отображается список трассировок. Каждая трассировка представляет собой набор действий, которые используют один и тот же идентификатор трассировки. Работа отслеживается с помощью отрезков, представляющих собой единицу работы. Обработка запроса ASP.NET создаст интервал. Выполнение запроса HttpClient будет интервалом. Отслеживая родительский диапазон, можно визуализировать иерархию диапазонов. Собирая диапазоны из каждого ресурса (процесса), мы отслеживаем работу, которая происходит в ряде служб. Http-запросы имеют заголовок, который используется для передачи traceId и родительского spanId в следующий сервис. Каждый ресурс должен собирать данные телеметрии и отправлять их одному сборщику. Затем он будет агрегировать и представлять иерархию диапазонов.

На панели мониторинга отобразится список трассировок с сводными сведениями. При каждом просмотре диапазона с новым идентификатором traceId они получат строку в таблице. При нажатии кнопки "Просмотреть" будут отображены все диапазоны в трассировке.

При выборе диапазона отображаются сведения, включая все свойства диапазона, например greeting тег, заданный на шаге 3.