Настройка Azure Monitor OpenTelemetry

В этом руководстве объясняется, как настроить OpenTelemetry (OTel) в Azure Monitor Application Insights с помощью дистрибутива OpenTelemetry Azure Monitor. Правильная конфигурация обеспечивает согласованную сбор данных телеметрии в .NET, Java, Node.jsи Python приложениях, что обеспечивает более надежный мониторинг и диагностику.

Примечание.

Сведения о приложениях-функциях Azure см. в разделе Use OpenTelemetry с Функции Azure.

строка подключения

В «Application Insights» строка подключения определяет целевое расположение для отправки данных телеметрии.

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

  • Добавьте UseAzureMonitor() в program.cs файл.

        var builder = WebApplication.CreateBuilder(args);
    
        // Add the OpenTelemetry telemetry service to the application.
        // This service will collect and send telemetry data to Azure Monitor.
        builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
            options.ConnectionString = "<YOUR-CONNECTION-STRING>";
        });
    
        var app = builder.Build();
    
        app.Run();
    
  • Задайте переменную среды.

    APPLICATIONINSIGHTS_CONNECTION_STRING=<YOUR-CONNECTION-STRING>
    
  • Добавьте следующий раздел в appsettings.json файл конфигурации.

      {
        "AzureMonitor": {
            "ConnectionString": "<YOUR-CONNECTION-STRING>"
        }
      }
    

Примечание.

Если задать строка подключения в нескольких местах, применяется следующий порядок приоритета:

  1. Код
  2. Переменная среды
  3. Файл конфигурации

Настройка имени облачной роли и экземпляра облачной роли

Для поддерживаемых языков дистрибутив Azure Monitor OpenTelemetry автоматически обнаруживает контекст ресурса и предоставляет значения по умолчанию для свойств Cloud Role Name и экземпляра роли в облаке вашего компонента. Однако может потребоваться переопределить значения по умолчанию на то, что имеет смысл для вашей команды. Значение имени облачной роли отображается на карте приложения в качестве имени под узлом.

Задайте имя облачной роли и экземпляр облачной роли через атрибуты Resource. Имя облачной роли использует атрибуты service.namespace и service.name, но переходит на service.name, если service.namespace не задан. Экземпляр облачной роли использует значение атрибута service.instance.id. Сведения о стандартных атрибутах ресурсов см. в разделе "Семантические соглашения OpenTelemetry".

// Setting role name and role instance

// Create a dictionary of resource attributes.
var resourceAttributes = new Dictionary<string, object> {
    { "service.name", "my-service" },
    { "service.namespace", "my-namespace" },
    { "service.instance.id", "my-instance" }};

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry()
    .UseAzureMonitor()
    // Configure the ResourceBuilder to add the custom resource attributes to all signals.
    // Custom resource attributes should be added AFTER AzureMonitor to override the default ResourceDetectors.
    .ConfigureResource(resourceBuilder => resourceBuilder.AddAttributes(resourceAttributes));

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Настройка атрибутов ресурсов

Автоматическое инструментирование и дистрибутивы Azure Monitor позволяют обнаруживать ресурсы, когда они выполняются в поддерживаемых средах Azure. Дополнительные сведения см. в разделе Автоматический сбор данных и детекторы ресурсов для Azure Monitor в OpenTelemetry.

Для настройки вручную задайте атрибуты ресурсов непосредственно с помощью стандартных параметров OpenTelemetry:

# Applies to .NET (ASP.NET/ASP.NET Core), Java, Node.js, and Python
export OTEL_SERVICE_NAME="my-service"
export OTEL_RESOURCE_ATTRIBUTES="cloud.provider=azure,cloud.region=westus,cloud.resource_id=/subscriptions/<SUB>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<APP>"

В PowerShell Windows:

$Env:OTEL_SERVICE_NAME="my-service"
$Env:OTEL_RESOURCE_ATTRIBUTES="cloud.provider=azure,cloud.region=westus,cloud.resource_id=/subscriptions/<SUB>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<APP>"

Включение выборки

Отбор данных снижает объем и стоимость обработки телеметрической информации. Azure Monitor дистрибутив OpenTelemetry поддерживает две стратегии отбора проб для трассировок и (при необходимости) позволяет синхронизировать журналы приложений с решениями по отбору проб трассировки. Самплер прикрепляет выбранный коэффициент выборки или частоту к экспортируемым трассировкам, чтобы Application Insights мог точно настроить учёт данных о нагрузках. Общие сведения см. в разделе " Дополнительные сведения о выборке".

Внимание

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

Примечание.

Если вы видите непредвиденные расходы или высокие затраты в Application Insights, распространенные причины включают высокий объем телеметрии, пики приема данных и неправильно настроенную выборку. Чтобы начать устранение неполадок, см. статью "Устранение проблем с высоким объемом данных в Application Insights".

Настройка выборки с помощью переменных среды

Используйте стандартные переменные среды OpenTelemetry, чтобы выбрать образец и указать его аргумент. Дополнительные сведения о типах отборщиков OpenTelemetry см. в OTEL_TRACES_SAMPLER.

  • OTEL_TRACES_SAMPLER тип семплера

    • microsoft.fixed_percentage — отбор части данных трассировки.
    • microsoft.rate_limited -" трассировки крышки в секунду.
  • OTEL_TRACES_SAMPLER_ARG Аргумент sampler

    • Для microsoft.fixed_percentage: значение в диапазоне 0.0–1.0 (например, 0.1 = ~10%).
    • Для microsoft.rate_limited: максимальные трассировки в секунду (например, 1.5).

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

Примечание.

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

Выборка фиксированного процента (~10%)

export OTEL_TRACES_SAMPLER="microsoft.fixed_percentage"
export OTEL_TRACES_SAMPLER_ARG=0.1

Выборка с ограничением скорости (~1,5 трассировок в секунду)

export OTEL_TRACES_SAMPLER="microsoft.rate_limited"
export OTEL_TRACES_SAMPLER_ARG=1.5

Настройка выборки в коде

Примечание.

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

Фиксированная процентная выборка

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    o.SamplingRatio = 0.1F; // ~10%
});
var app = builder.Build();
app.Run();

Выборка с ограничением скорости

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    o.TracesPerSecond = 1.5; // ~1.5 traces/sec
});
var app = builder.Build();
app.Run();

Примечание.

Если вы не задаете пример в коде или с помощью переменных среды, Azure Monitor использует ApplicationInsightsSampler по умолчанию.

Совет

При использовании выборки с фиксированным процентом и вы не знаете, какое значение следует задать для частоты выборки, начните с 5% (0.05). Настройте частоту на основе точности операций, отображаемых в панелях ошибок и производительности. Любая выборка снижает точность, поэтому следует обращать внимание на метрики OpenTelemetry, которые не зависят от выборки.

Настройка выборки в файле конфигурации

Настройка выборки в файле конфигурации не поддерживается для ASP.NET Core. Чтобы настроить выборку, используйте вместо этого переменные кода или среды.

Настройка выборки на основе трассировки для журналов

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

  • Запись журнала является частью трассировки при наличии допустимой SpanId.
  • Если связанная трассировка TraceFlags указывает "не отсортирован", функция удаляет запись журнала.
  • Записи журнала без контекста трассировки не затрагиваются .
  • Эта функция включена по умолчанию.

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

builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    o.EnableTraceBasedLogsSampler = true;
});

Живые метрики

Динамические метрики предоставляют панель мониторинга аналитики в режиме реального времени для анализа активности приложений и производительности.

Внимание

Ознакомьтесь с Дополнительными условиями использования для предварительных версий Microsoft Azure, чтобы узнать правовые условия, применимые к функциям Azure, которые находятся в бета-версии, предварительной версии или иным образом еще не выпущены в общий доступ.

По умолчанию эта функция включена.

Пользователи могут отключить динамические метрики при настройке дистрибутива.

builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
	// Disable the Live Metrics feature.
    options.EnableLiveMetrics = false;
});

Включение проверки подлинности Microsoft Entra ID (ранее Azure AD)

Чтобы создать более безопасное подключение к Azure, включите проверку подлинности Microsoft Entra. Этот метод аутентификации предотвращает добавление неавторизованных телеметрических данных в вашу подписку.

Дополнительные сведения см. на специальной странице проверки подлинности Microsoft Entra, связанной для всех поддерживаемых языков.

Сведения о настройке аутентификации Entra ID см. в разделе аутентификация Microsoft Entra для Application Insights.

Автономное хранилище и автоматические повторные попытки

Предложения OpenTelemetry от Azure Monitor кэшируют данные телеметрии, когда приложение отключается от Application Insights, и пытаются снова отправлять данные до 48 часов. Рекомендации по обработке данных см. в разделе "Экспорт и удаление частных данных". Приложения с высокой нагрузкой иногда сбрасывают данные телеметрии по двум причинам: превышение допустимого времени или превышение максимального размера файла. При необходимости продукт определяет последние события по сравнению со старыми.

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

  • Windows

    • %LOCALAPPDATA%\Microsoft\AzureMonitor
    • %TEMP%\Microsoft\AzureMonitor
  • Не Windows

    • %TMPDIR%/Microsoft/AzureMonitor
    • /var/tmp/Microsoft/AzureMonitor
    • /tmp/Microsoft/AzureMonitor

Чтобы переопределить каталог по умолчанию, необходимо задать значение AzureMonitorOptions.StorageDirectory.

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
{
    // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
    // This is the directory where the OpenTelemetry SDK will store any telemetry data that can't be sent to Azure Monitor immediately.
    options.StorageDirectory = "C:\\SomeDirectory";
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Чтобы отключить эту функцию, установите AzureMonitorOptions.DisableOfflineStorage = true.

Включить экспортёр OTLP

Возможно, вы захотите включить экспортер OpenTelemetry (OTLP) вместе с экспортером Azure Monitor, чтобы отправлять данные телеметрии в два расположения.

Примечание.

Экспортёр OTLP представлен только для удобства. Microsoft официально не поддерживает OTLP Exporter или любые компоненты или сторонние проекты, зависящие от него.

  1. Установите пакет OpenTelemetry.Exporter.OpenTelemetryProtocol в проекте.

    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
    
  2. Добавьте приведенный ниже фрагмент кода. В этом примере предполагается, что у вас есть сборщик OpenTelemetry с работающим приемником OTLP. Дополнительные сведения см. в разделе example на GitHub.

    // Create a new ASP.NET Core web application builder.
    var builder = WebApplication.CreateBuilder(args);
    
    // Add the OpenTelemetry telemetry service to the application.
    // This service will collect and send telemetry data to Azure Monitor.
    builder.Services.AddOpenTelemetry().UseAzureMonitor();
    
    // Add the OpenTelemetry OTLP exporter to the application.
    // This exporter will send telemetry data to an OTLP receiver, such as Prometheus
    builder.Services.AddOpenTelemetry().WithTracing(builder => builder.AddOtlpExporter());
    builder.Services.AddOpenTelemetry().WithMetrics(builder => builder.AddOtlpExporter());
    
    // Build the ASP.NET Core web application.
    var app = builder.Build();
    
    // Start the ASP.NET Core web application.
    app.Run();
    

Конфигурации OpenTelemetry

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

Переменная среды Описание
APPLICATIONINSIGHTS_CONNECTION_STRING Установите эту переменную на строку подключения, связанную с ресурсом Application Insights.
APPLICATIONINSIGHTS_STATSBEAT_DISABLED Установите переменную true, чтобы отказаться от внутренней коллекции метрик.
OTEL_RESOURCE_ATTRIBUTES Пары "ключ-значение" для использования в качестве атрибутов ресурсов. Дополнительные сведения об атрибутах ресурсов см. в спецификации пакета SDK для ресурсов.
OTEL_SERVICE_NAME Задает значение атрибута service.name ресурса. Если service.name также указан в OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME имеет приоритет.

Редактировать строки запроса URL-адреса

Чтобы изменить строки запроса URL-адреса, отключите коллекцию строк запроса. Этот параметр рекомендуется использовать при вызове хранилища Azure с помощью маркера SAS.

При использовании дистрибутивного пакета Azure.Monitor.OpenTelemetry.AspNetCore, он включает библиотеки инструментирования ASP.NET Core и HttpClient. Пакет дистрибутива по умолчанию отключает сокрытие строк запроса.

Чтобы изменить это поведение, задайте для переменной среды значение true или false.

  • ASP.NET Core инструментирование: по умолчанию отключена функция сокрытия строки запроса OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION. Чтобы включить, задайте для этой переменной среды значение false.

  • Инструментирование клиента Http. OTEL_DOTNET_EXPERIMENTAL_HTTPCLIENT_DISABLE_URL_QUERY_REDACTION По умолчанию параметр "Редактация строки запроса" отключен. Чтобы включить, задайте для этой переменной среды значение false.

Интервал экспорта метрик

Можно настроить интервал экспорта метрик с помощью переменной OTEL_METRIC_EXPORT_INTERVAL среды.

OTEL_METRIC_EXPORT_INTERVAL=60000

Значение по умолчанию — 60000 миллисекунда (60 секунд). Этот параметр определяет, как часто пакет SDK OpenTelemetry экспортирует метрики.

Совет

Azure Monitor метрики и Azure Monitor Workspace принимают пользовательские метрики с фиксированным интервалом в 60 секунд. Метрики, отправленные чаще, буфериируются и обрабатываются каждые 60 секунд. В Log Analytics метрики записываются в тот интервал, в котором они отправляются, что может увеличить затраты при более коротких интервалах и задерживать видимость при более длинных.

Дополнительные сведения см. в следующих спецификациях OpenTelemetry:

Устранение неполадок, обратная связь и поддержка

Совет

Во всех статьях о дистрибутивах OpenTelemetry доступны следующие разделы.

Troubleshooting

Сведения об устранении неполадок см. в статье Устранение проблем с OpenTelemetry в .NET и Устранение неполадок с отсутствием данных телеметрии приложений в Azure Monitor Application Insights.

Отзывы о OpenTelemetry

Чтобы оставить отзыв, сделайте следующее:

Поддержка

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

  • Для вопросов технической поддержки Azure откройте заявку в поддержку Azure.
  • По вопросам, связанным с OpenTelemetry, обратитесь непосредственно к сообществу OpenTelemetry .NET.
  • Список открытых вопросов, связанных с экспортером Azure Monitor, можно найти на странице с проблемами на GitHub.

Дальнейшие действия