Поделиться через

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

  • Статья

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

Помимо стандартной части .NET Aspire, панель мониторинга Aspire доступна как автономный контейнер docker, который предоставляет телеметрию конечной точки OTLP, в которую можно отправлять данные телеметрии конечной точки 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!";
}

Примечание.

Определение конечной точки не использует ничего конкретного для OpenTelemetry. Он использует API .NET для наблюдения.

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>

Примечание.

Используйте последние версии, так как API OTel постоянно развиваются.

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 для определения атрибутов ресурсов.

Примечание.

Распространенная хотка заключается в том, чтобы смешать AppSettings.json и AppSettings.Development.json, если последний присутствует, он будет использоваться при использовании F5 из Visual Studio и любых параметров в AppSettings.json будет игнорироваться.

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

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

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

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

[Панель мониторинга Aspire]

Скопируйте отображаемый 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. Результаты гистограммы могут включать примеры, которые являются отдельными точками данных вместе с трассировкой или spanId для этого запроса. Они будут отображаться как точки на графе. При выборе соответствующих трассировок вы увидите, что произошло с этим значением. Это полезно для диагностики вылитых.
  • Метрики могут включать измерения, которые являются парами "ключ-значение", связанными с отдельными значениями. Значения агрегируются на измерение. С помощью раскрывающихся списков в представлении можно отфильтровать результаты для просмотра определенных измерений, таких как только GET запросы, или для определенного URL-маршрута в ASP.NET.

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

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

Трассировки на автономной панели мониторинга

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

Диапазоны на автономной панели мониторинга

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