Наблюдаемость .NET с помощью OpenTelemetry

Статья
10/25/2024

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

Что такое наблюдаемость?

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

Наблюдаемость обычно выполняется с помощью сочетания:

Журналы, которые записывают отдельные операции, такие как входящий запрос, сбой в определенном компоненте или размещение заказа.
Метрики, которые измеряют счетчики и датчики, такие как количество завершенных запросов, активные запросы, мини-приложения, проданные; или гистограмма задержки запроса.
Распределенная трассировка, которая отслеживает запросы и действия между компонентами в распределенной системе, чтобы увидеть, где время тратится и отслеживает конкретные сбои.

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

Каждый компонент может включать данные телеметрии из:

Среда выполнения .NET, например сборщик мусора или компилятор JIT.
Библиотеки, например из Kestrel (веб-сервер ASP.NET) и HttpClient.
Данные телеметрии для конкретных приложений, создаваемые кодом.

Подходы к наблюдаемости в .NET

Существует несколько различных способов достижения наблюдаемости в приложениях .NET:

Явно в коде, ссылаясь и используя библиотеку, например OpenTelemetry. Если у вас есть доступ к исходному коду и можно перестроить приложение, то это самый мощный и настраиваемый механизм.
Внепроцессное использование EventPipe. Такие средства, как dotnet-monitor , могут прослушивать журналы и метрики, а затем обрабатывать их без влияния на код.
С помощью перехватчика запуска сборки можно внедрить в процесс, который затем может собирать инструментирование. Примером этого подхода является автоматическое инструментирование OpenTelemetry .NET.

Что такое OpenTelemetry?

OpenTelemetry (OTel) — это кроссплатформенный стандарт для сбора и создания данных телеметрии. OpenTelemetry включает:

API для библиотек, используемых для записи данных телеметрии в виде кода.
API, которые разработчики приложений используют для настройки того, какая часть записанных данных будет отправлена по сети, где она будет отправлена, а также как она может быть отфильтрована, буферирована, обогащена и преобразована.
Семантические соглашения предоставляют рекомендации по именованию и содержимому данных телеметрии. Важно для приложений, которые создают данные телеметрии и средства, которые получают данные, чтобы договориться о различных типах данных и о том, какие виды данных полезны, чтобы средства могли обеспечить эффективный анализ.
Интерфейс для экспортеров. Экспортеры — это подключаемые модули, которые позволяют передавать данные телеметрии в определенных форматах в разные серверные серверы телеметрии.
Протокол проводной передачи OTLP — это нейтральный сетевой протокол поставщика для передачи данных телеметрии. Некоторые средства и поставщики поддерживают этот протокол в дополнение к существующим собственным протоколам, которые они могут иметь.

Использование OTel позволяет использовать широкий спектр систем APM, включая системы с открытым исходным кодом, такие как Prometheus и Grafana, Azure Monitor — продукт APM Корпорации Майкрософт в Azure или многие поставщики APM, которые сотрудничают с OpenTelemetry.

Существуют реализации OpenTelemetry для большинства языков и платформ, включая .NET.

Реализация .NET OpenTelemetry

Реализация .NET OpenTelemetry немного отличается от других платформ, так как .NET предоставляет api ведения журнала, метрик и действий в платформе. Это означает, что OTel не должен предоставлять API-интерфейсы для использования авторами библиотеки. Реализация OTel .NET использует эти API платформы для инструментирования:

Архитектура OTel .NET

Где OTel вступает в игру, это то, что он собирает данные телеметрии из этих API и других источников (через библиотеки инструментирования), а затем экспортирует их в систему мониторинга производительности приложений (APM) для хранения и анализа. Преимущество OTel представляет собой стандартный отраслевый механизм сбора, общих схем и семантики для данных телеметрии, а также API для интеграции API с OTel. Использование OTel означает, что приложения не должны использовать API-интерфейсы или структуры данных, относящиеся к APM; они работают против стандарта OTel. API могут реализовать определенный компонент экспортера APM или использовать OTLP, который является новым стандартом провода для экспорта данных телеметрии в системы APM.

Пакеты OpenTelemetry

OpenTelemetry в .NET реализуется в виде ряда пакетов NuGet, которые образуют несколько категорий:

Core API
Инструментирование — эти пакеты собирают инструментирование из среды выполнения и общих библиотек.
Экспортеры — эти интерфейсы с системами APM, такими как Prometheus, Jaeger и OTLP.

В следующей таблице описаны основные пакеты.

Название пакета	Description
OpenTelemetry	Основная библиотека, предоставляющая основные функции OTEL
OpenTelemetry.Instrumentation.AspNetCore	Инструментирование для ASP.NET Core и Kestrel
OpenTelemetry.Instrumentation.GrpcNetClient	Инструментирование для клиента gRPC для отслеживания исходящих вызовов gRPC
OpenTelemetry.Instrumentation.Http	Инструментирование для `HttpClient` и `HttpWebRequest` отслеживание исходящих HTTP-вызовов
OpenTelemetry.Instrumentation.SqlClient	Инструментирование для `SqlClient` отслеживания операций базы данных
OpenTelemetry.Exporter.Console	Экспортер консоли, который обычно используется для диагностики экспортируемых данных телеметрии
OpenTelemetry.Exporter.OpenTelemetryProtocol	Экспортер с помощью протокола OTLP
OpenTelemetry.Exporter.Prometheus.AspNetCore	Экспорт для Prometheus реализован с помощью конечной точки ASP.NET Core
OpenTelemetry.Exporter.Zipkin	Экспортер трассировки Zipkin

Примеры

Этот раздел продолжается с несколькими примерами пошагового руководства по использованию OpenTelemetry в .NET:

OpenTelemetry в .NET Aspire

.NET Aspire — это набор расширений для .NET, чтобы упростить создание и работу с распределенными приложениями. Одним из преимуществ использования .NET Aspire является встроенная телеметрия с помощью библиотек OpenTelemetry для .NET. Шаблоны проектов по умолчанию для .NET Aspire содержат ServiceDefaults проект, часть которого состоит в настройке и настройке OTel. Проект По умолчанию службы ссылается и инициализируется каждой службой в решении .NET Aspire.

Шаблон проекта по умолчанию службы включает пакеты sdk OTel, ASP.NET, HttpClient и инструментирование среды выполнения и настраиваются в Extensions.cs файле. Для экспорта телеметрии .NET Aspire включает экспортер OTLP по умолчанию, чтобы обеспечить визуализацию телеметрии с помощью панели мониторинга Aspire.

Панель мониторинга Aspire предназначена для передачи наблюдения телеметрии в локальный цикл отладки, что позволяет разработчикам не только обеспечивать, чтобы приложения создавали данные телеметрии, но и используют эти данные телеметрии для диагностики этих приложений локально. Возможность наблюдать за вызовами между службами оказывается столь же полезной во время отладки, как в рабочей среде. Панель мониторинга .NET Aspire запускается автоматически при F5 AppHost проекта из Visual Studio или dotnet run AppHost проекта.

Дополнительные сведения о .NET Aspire см. в следующем разделе:

Повторное выполнение проекта по умолчанию службы без оркестрации .NET Aspire

Вероятно, самый простой способ настроить OTel для проектов ASP.NET заключается в использовании проекта Aspire Service Defaults, даже если не используется остальная часть .NET Aspire, например AppHost для оркестрации. Проект По умолчанию службы доступен в качестве шаблона проекта с помощью Visual Studio или dotnet new. Он настраивает OTel и настраивает экспортер OTLP. Затем можно использовать переменные среды OTel для настройки конечной точки OTLP для отправки данных телеметрии и предоставления свойств ресурса для приложения.

Ниже приведены действия по использованию ServiceDefaults за пределами .NET Aspire:

Добавьте проект ServiceDefaults в решение с помощью добавления нового проекта в Visual Studio или используйтеdotnet new aspire-servicedefaults --output ServiceDefaults
Ссылка на проект ServiceDefaults из приложения ASP.NET. В Visual Studio используйте команду "Добавить —> справочник по проекту" и выберите проект ServiceDefaults "
Вызовите функцию установки OpenTelemetry в рамках инициализации построителя приложений.

var builder = WebApplication.CreateBuilder(args);
builder.ConfigureOpenTelemetry();

var app = builder.Build();

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

app.Run();

По умолчанию службы можно настроить следующие дополнительные функциональные возможности при необходимости с помощью AddServiceDefaults() или определенных функций:

Проверка работоспособности с /health конечными точками и /alive конечными точками
Обнаружение служб, которое будет без остальной части .NET Aspire
Настройка устойчивости для HttpClient, которая повторит запрос в случае сбоев

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