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

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

Примечание.

Сведения о приложениях-функциях Azure см. в статье "Использование 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>"
    }
  }
```

Примечание.

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

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

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

Добавьте экспортер Azure Monitor к каждому сигналу OpenTelemetry в запуске приложения.

    // Create a new OpenTelemetry tracer provider.
    // It is important to keep the TracerProvider instance active throughout the process lifetime.
    var tracerProvider = Sdk.CreateTracerProviderBuilder()
        .AddAzureMonitorTraceExporter(options =>
        {
            options.ConnectionString = "<YOUR-CONNECTION-STRING>";
        })
        .Build();

    // Create a new OpenTelemetry meter provider.
    // It is important to keep the MetricsProvider instance active throughout the process lifetime.
    var metricsProvider = Sdk.CreateMeterProviderBuilder()
        .AddAzureMonitorMetricExporter(options =>
        {
            options.ConnectionString = "<YOUR-CONNECTION-STRING>";
        })
        .Build();

    // Create a new logger factory.
    // It is important to keep the LoggerFactory instance active throughout the process lifetime.
    var loggerFactory = LoggerFactory.Create(builder =>
    {
        builder.AddOpenTelemetry(logging =>
        {
            logging.AddAzureMonitorLogExporter(options =>
            {
                options.ConnectionString = "<YOUR-CONNECTION-STRING>";
            });
        });
    });

Задайте переменную среды.

APPLICATIONINSIGHTS_CONNECTION_STRING=<YOUR-CONNECTION-STRING>

Примечание.

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

Код
Переменная среды

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

Задайте переменную среды.

APPLICATIONINSIGHTS_CONNECTION_STRING=<YOUR-CONNECTION-STRING>

Задайте свойство.

applicationinsights.connection.string=<YOUR-CONNECTION-STRING>

Совет

Примеры TypeScript для Azure Monitor OpenTelemetry (достоверный источник четности): https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/monitor/monitor-opentelemetry/samples-dev/src

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

Задайте переменную среды.

APPLICATIONINSIGHTS_CONNECTION_STRING=<YOUR-CONNECTION-STRING>

Используйте объект конфигурации.

export class BasicConnectionSample {
  static async run() {
    const { useAzureMonitor } = await import("@azure/monitor-opentelemetry");
    const options = {
      azureMonitorExporterOptions: {
        connectionString:
          process.env.APPLICATIONINSIGHTS_CONNECTION_STRING || "<YOUR-CONNECTION-STRING>",
      },
    };
    const monitor = useAzureMonitor(options);
    console.log("Azure Monitor initialized");
  }
}

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

Задайте переменную среды.

APPLICATIONINSIGHTS_CONNECTION_STRING=<YOUR-CONNECTION-STRING>

Используйте функцию configure_azure_monitor .

# Import the `configure_azure_monitor()` function from the `azure.monitor.opentelemetry` package.
from azure.monitor.opentelemetry import configure_azure_monitor

# Configure OpenTelemetry to use Azure Monitor with the specified connection string.
# Replace `<YOUR-CONNECTION-STRING>` with the connection string of your Azure Monitor Application Insights resource.
configure_azure_monitor(
    connection_string="<YOUR-CONNECTION-STRING>",
)

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

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

Задайте имя и экземпляр облачной роли с помощью атрибутов 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();

// 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 resource builder.
var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);

// Create a new OpenTelemetry tracer provider and set the resource builder.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    // Set ResourceBuilder on the TracerProvider.
    .SetResourceBuilder(resourceBuilder)
    .AddAzureMonitorTraceExporter()
    .Build();

// Create a new OpenTelemetry meter provider and set the resource builder.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    // Set ResourceBuilder on the MeterProvider.
    .SetResourceBuilder(resourceBuilder)
    .AddAzureMonitorMetricExporter()
    .Build();

// Create a new logger factory and add the OpenTelemetry logger provider with the resource builder.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(logging =>
    {
        // Set ResourceBuilder on the Logging config.
        logging.SetResourceBuilder(resourceBuilder);
        logging.AddAzureMonitorLogExporter();
    });
});

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

Используйте spring.application.name для встроенных приложений образов Spring Boot.
Используйте собственные приложения образов quarkus.application.name Quarkus.

Примечание.

Сообщество Quarkus поддерживает и обслуживает расширения Quarkus. Для получения справки используйте каналы поддержки сообщества Quarkus. Корпорация Майкрософт не предоставляет техническую поддержку этой интеграции.

export class CloudRoleSample {
  static async run() {
    const { useAzureMonitor } = await import("@azure/monitor-opentelemetry");
    const { resourceFromAttributes } = await import("@opentelemetry/resources");
    const { ATTR_SERVICE_NAME } = await import("@opentelemetry/semantic-conventions");
    const { ATTR_SERVICE_NAMESPACE, ATTR_SERVICE_INSTANCE_ID } =
      await import("@opentelemetry/semantic-conventions/incubating");

    const customResource = resourceFromAttributes({
      [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || "my-service",
      [ATTR_SERVICE_NAMESPACE]: process.env.OTEL_SERVICE_NAMESPACE || "my-namespace",
      [ATTR_SERVICE_INSTANCE_ID]: process.env.OTEL_SERVICE_INSTANCE_ID || "my-instance",
    });

    const options = {
      resource: customResource,
      azureMonitorExporterOptions: {
        connectionString:
          process.env.APPLICATIONINSIGHTS_CONNECTION_STRING || "<YOUR-CONNECTION-STRING>",
      },
    };

    const monitor = useAzureMonitor(options);
    console.log("Azure Monitor initialized (custom resource)");
  }
}

Задайте атрибуты ресурса с помощью OTEL_RESOURCE_ATTRIBUTES переменных среды и /или OTEL_SERVICE_NAME среды. OTEL_RESOURCE_ATTRIBUTES принимает ряд пар "ключ-значение", разделенных запятыми. Например, чтобы задать имя my-namespace.my-helloworld-service облачной роли и задать для my-instanceэкземпляра облачной роли значение, можно задать OTEL_RESOURCE_ATTRIBUTES и OTEL_SERVICE_NAME так:

export OTEL_RESOURCE_ATTRIBUTES="service.namespace=my-namespace,service.instance.id=my-instance"
export OTEL_SERVICE_NAME="my-helloworld-service"

Если атрибут resource не задан, можно также задать имя облачной service.namespace роли только с переменной среды OTEL_SERVICE_NAME или атрибутом service.name Resource. Например, чтобы задать имя my-helloworld-service облачной роли и задать для my-instanceэкземпляра облачной роли значение, можно задать OTEL_RESOURCE_ATTRIBUTES и OTEL_SERVICE_NAME так:

export OTEL_RESOURCE_ATTRIBUTES="service.instance.id=my-instance"
export OTEL_SERVICE_NAME="my-helloworld-service"

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

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

Внимание

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

Примечание.

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

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

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

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).

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

Выборка фиксированного процента (~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 по умолчанию.

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

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter(o => o.SamplingRatio = 0.1F)
    .Build();

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

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter(o => o.TracesPerSecond = 1.5F)
    .Build();

Примечание.

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

const { useAzureMonitor } = await import("@azure/monitor-opentelemetry");
const monitor = useAzureMonitor({
  samplingRatio: 0.1, // ~10%
  azureMonitorExporterOptions: {
    connectionString:
      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING || "<YOUR-CONNECTION-STRING>",
  },
});

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

const { useAzureMonitor } = await import("@azure/monitor-opentelemetry");
const monitor = useAzureMonitor({
  tracesPerSecond: 1.5, // ~1.5 traces/sec
  azureMonitorExporterOptions: {
    connectionString:
      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING || "<YOUR-CONNECTION-STRING>",
  },
});

Примечание.

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

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    connection_string="<YOUR-CONNECTION-STRING>",
    sampling_ratio=0.1, # 0.1 = 10% of traces sampled
)

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

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    connection_string="<YOUR-CONNECTION-STRING>",
    traces_per_second=1.5, # ~1.5 traces/sec
)

Примечание.

Если вы не задаете переменные среды и не предоставляете ни sampling_ratio, ни traces_per_second, то configure_azure_monitor() по умолчанию использует ApplicationInsightsSampler.

Совет

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

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

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

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

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

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

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter(o => o.EnableTraceBasedLogsSampler = true)
    .Build();

const { useAzureMonitor } = await import("@azure/monitor-opentelemetry");
const monitor = useAzureMonitor({
  enableTraceBasedSamplingForLogs: true,
  azureMonitorExporterOptions: {
    connectionString:
      process.env.APPLICATIONINSIGHTS_CONNECTION_STRING || "<YOUR-CONNECTION-STRING>",
  },
});

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    connection_string="<YOUR-CONNECTION-STRING>",
    enable_trace_based_sampling_for_logs=True,
)

Динамические метрики

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

Внимание

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

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

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

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

Внимание

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

export class LiveMetricsSample {
  static async run() {
    const { useAzureMonitor } = await import("@azure/monitor-opentelemetry");
    const options = {
      azureMonitorExporterOptions: {
        connectionString:
          process.env.APPLICATIONINSIGHTS_CONNECTION_STRING || "<YOUR-CONNECTION-STRING>",
      },
      enableLiveMetrics: true, // set to false to disable
    };
    const monitor = useAzureMonitor(options);
    console.log("Azure Monitor initialized (live metrics enabled)");
  }
}

Внимание

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

...
configure_azure_monitor(
	enable_live_metrics=True
)
...

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

Возможно, потребуется включить проверку подлинности Microsoft Entra для более безопасного подключения к Azure, что предотвращает прием неавторизованных данных телеметрии в подписку.

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

Дополнительные сведения о настройке аутентификации Entra ID см. в статье Microsoft Entra Authentication for Application Insights

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

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

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

Виндоус
- %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

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

Виндоус
- %LOCALAPPDATA%\Microsoft\AzureMonitor
- %TEMP%\Microsoft\AzureMonitor
Не в Windows
- %TMPDIR%/Microsoft/AzureMonitor
- /var/tmp/Microsoft/AzureMonitor
- /tmp/Microsoft/AzureMonitor

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

// Create a new OpenTelemetry tracer provider and set the storage directory.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter(options =>
    {
        // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
        // This is the directory where the OpenTelemetry SDK will store any trace data that can't be sent to Azure Monitor immediately.
        options.StorageDirectory = "C:\\SomeDirectory";
        })
        .Build();

// Create a new OpenTelemetry meter provider and set the storage directory.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter(options =>
    {
        // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
        // This is the directory where the OpenTelemetry SDK will store any metric data that can't be sent to Azure Monitor immediately.
        options.StorageDirectory = "C:\\SomeDirectory";
        })
        .Build();

// Create a new logger factory and add the OpenTelemetry logger provider with the storage directory.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(logging =>
    {
        logging.AddAzureMonitorLogExporter(options =>
        {
            // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
            // This is the directory where the OpenTelemetry SDK will store any log data that can't be sent to Azure Monitor immediately.
            options.StorageDirectory = "C:\\SomeDirectory";
        });
    });
});

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

Если агент не может отправлять данные телеметрии в Azure Monitor, он хранит файлы телеметрии на диске. Файлы сохраняются в telemetry папке в каталоге, указанном системным свойством java.io.tmpdir . Каждое имя файла начинается с метки времени и заканчивается расширением .trn . Этот механизм автономного хранилища помогает обеспечить хранение данных телеметрии во время временных сбоев сети или сбоев приема.

Агент хранит до 50 МБ данных телеметрии по умолчанию и разрешает настройку ограничения хранилища. Попытки отправки хранимой телеметрии периодически выполняются. Файлы телеметрии старше 48 часов удаляются, а самые старые события удаляются при достижении ограничения хранилища.

Полный список доступных конфигураций см. в разделе "Параметры конфигурации".

Агент хранит до 50 МБ данных телеметрии по умолчанию. Попытки отправки хранимой телеметрии периодически выполняются. Файлы телеметрии старше 48 часов удаляются, а самые старые события удаляются при достижении ограничения хранилища.

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

Виндоус
- %TEMP%\Microsoft-AzureMonitor-<unique-identifier>\opentelemetry-nodejs-<your-instrumentation-key>
Не в Windows
- %TMPDIR%/Microsoft/Microsoft-AzureMonitor-<unique-identifier>/opentelemetry-nodejs-<your-instrumentation-key>
- /var/tmp/Microsoft/Microsoft-AzureMonitor-<unique-identifier>/opentelemetry-nodejs-<your-instrumentation-key>

Это <unique-identifier> хэш, созданный из атрибутов пользовательской среды, таких как ключ инструментирования, имя процесса, имя пользователя и каталог приложения. Этот идентификатор решает общую проблему системы с несколькими пользователями: когда первый пользователь создает каталог хранилища, их разрешения на файл (параметры umask) могут блокировать доступ к тому же пути другим пользователям. Уникальный каталог для каждого контекста пользователя гарантирует, что каждый пользователь получает собственное расположение хранилища с соответствующими разрешениями на доступ.

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

Например:

export class OfflineStorageSample {
  static async run() {
    const { useAzureMonitor } = await import("@azure/monitor-opentelemetry");
    const options = {
      azureMonitorExporterOptions: {
        connectionString:
          process.env.APPLICATIONINSIGHTS_CONNECTION_STRING || "<YOUR-CONNECTION-STRING>",
        storageDirectory: "C:\\\\SomeDirectory",
        disableOfflineStorage: false, // set to true to disable
      },
    };
    const monitor = useAzureMonitor(options);
    console.log("Azure Monitor initialized (offline storage configured)");
  }
}

Чтобы отключить эту функцию, следует задать.disableOfflineStorage = true

По умолчанию экспортеры Azure Monitor используют следующий путь:

<tempfile.gettempdir()>/Microsoft-AzureMonitor-<unique-identifier>/opentelemetry-python-<your-instrumentation-key>

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

Например:

...
# Configure OpenTelemetry to use Azure Monitor with the specified connection string and storage directory.
# Replace `<YOUR-CONNECTION-STRING>` with the connection string to your Azure Monitor Application Insights resource.
# Replace `C:\\SomeDirectory` with the directory where you want to store the telemetry data before it is sent to Azure Monitor.
configure_azure_monitor(
    connection_string="<YOUR-CONNECTION-STRING>",
    storage_directory="C:\\SomeDirectory",
)
...

Чтобы отключить эту функцию, необходимо задать значение disable_offline_storageTrue. По умолчанию — False.

Например:

...
# Configure OpenTelemetry to use Azure Monitor with the specified connection string and disable offline storage.
# Replace `<YOUR-CONNECTION-STRING>` with the connection string to your Azure Monitor Application Insights resource.
configure_azure_monitor(
    connection_string="<YOUR-CONNECTION-STRING>",
    disable_offline_storage=True,
)
...

Включение средства экспорта OTLP

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

Примечание.

Средство экспорта OTLP отображается только для удобства. Корпорация Майкрософт официально не поддерживает средство экспорта OTLP, а также все подчиненные компоненты и сторонние средства.

Установите пакет OpenTelemetry.Exporter.OpenTelemetryProtocol в проекте.
```
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
```

Добавьте приведенный ниже фрагмент кода. В этом примере предполагается, что у вас есть сборщик OpenTelemetry с работающим приемником OTLP. Дополнительные сведения см. в примере на сайте 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.Exporter.OpenTelemetryProtocol в проекте.
```
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
```

    // Create a new OpenTelemetry tracer provider and add the Azure Monitor trace exporter and the OTLP trace exporter.
    // It is important to keep the TracerProvider instance active throughout the process lifetime.
    var tracerProvider = Sdk.CreateTracerProviderBuilder()
        .AddAzureMonitorTraceExporter()
        .AddOtlpExporter()
        .Build();

    // Create a new OpenTelemetry meter provider and add the Azure Monitor metric exporter and the OTLP metric exporter.
    // It is important to keep the MetricsProvider instance active throughout the process lifetime.
    var metricsProvider = Sdk.CreateMeterProviderBuilder()
        .AddAzureMonitorMetricExporter()
        .AddOtlpExporter()
        .Build();

Установите экспортер трассировки сборщика OpenTelemetry и другие пакеты OpenTelemetry в проекте.

npm install @opentelemetry/api
npm install @opentelemetry/exporter-trace-otlp-http
npm install @opentelemetry/sdk-trace-base
npm install @opentelemetry/sdk-trace-node

export class OtlpExporterSample {
  static async run() {
    const { useAzureMonitor } = await import("@azure/monitor-opentelemetry");
    const { BatchSpanProcessor } = await import("@opentelemetry/sdk-trace-base");
    const { OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-http");

    // Create an OTLP trace exporter (set 'url' if your collector isn't on the default endpoint).
    const otlpExporter = new OTLPTraceExporter({
      // url: "http://localhost:4318/v1/traces",
    });

    // Configure Azure Monitor and add the OTLP exporter as an additional span processor.
    const options = {
      azureMonitorExporterOptions: {
        connectionString:
          process.env.APPLICATIONINSIGHTS_CONNECTION_STRING || "<YOUR-CONNECTION-STRING>",
      },
      spanProcessors: [new BatchSpanProcessor(otlpExporter)],
    };

    const monitor = useAzureMonitor(options);
    console.log("Azure Monitor initialized (OTLP exporter added)");
  }
}

Установите пакет opentelemetry-exporter-otlp .

Добавьте приведенный ниже фрагмент кода. В этом примере предполагается, что у вас есть сборщик OpenTelemetry с работающим приемником OTLP. Дополнительные сведения см. в этой статье README.

    # Import the `configure_azure_monitor()`, `trace`, `OTLPSpanExporter`, and `BatchSpanProcessor` classes from the appropriate packages.
    from azure.monitor.opentelemetry import configure_azure_monitor
    from opentelemetry import trace
    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
    from opentelemetry.sdk.trace.export import BatchSpanProcessor

    # Configure OpenTelemetry to use Azure Monitor with the specified connection string.
    # Replace `<YOUR-CONNECTION-STRING>` with the connection string to your Azure Monitor Application Insights resource.
    configure_azure_monitor(
        connection_string="<YOUR-CONNECTION-STRING>",
    )

    # Get the tracer for the current module.
    tracer = trace.get_tracer(__name__) 

    # Create an OTLP span exporter that sends spans to the specified endpoint.
    # Replace `http://localhost:4317` with the endpoint of your OTLP collector.
    otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4317")

    # Create a batch span processor that uses the OTLP span exporter.
    span_processor = BatchSpanProcessor(otlp_exporter)

    # Add the batch span processor to the tracer provider.
    trace.get_tracer_provider().add_span_processor(span_processor)

    # Start a new span with the name "test".
    with tracer.start_as_current_span("test"):
        print("Hello world!")

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

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

Переменная среды	Описание
`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` то имеет приоритет.

Переменная среды	Описание
`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` то имеет приоритет.

Переменная среды	Описание
`APPLICATIONINSIGHTS_CONNECTION_STRING`	Задайте для ресурса Application Insights строка подключения.

Для собственных приложений Spring Boot доступны конфигурации пакета SDK для Java OpenTelemetry .

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

Примечание.

Строки запроса URL-адреса Redact

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

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

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

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

При использовании Azure.Monitor.OpenTelemetry.Exporter необходимо вручную включить библиотеки ASP.NET Core или HttpClient Instrumentation в конфигурацию OpenTelemetry. Эти библиотеки инструментирования включают Redaction QueryString по умолчанию.

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

ASP.NET основное инструментирование. OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION По умолчанию включена редактация строки запроса. Чтобы отключить эту переменную среды, задайте для trueнее значение .
Инструментирование клиента Http: OTEL_DOTNET_EXPERIMENTAL_HTTPCLIENT_DISABLE_URL_QUERY_REDACTION по умолчанию включена редактация строки запроса. Чтобы отключить эту переменную среды, задайте для trueнее значение .

Добавьте следующее applicationinsights.json в файл конфигурации:

{
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.query",
            "pattern": "^.*$",
            "replace": "REDACTED",
            "action": "mask"
          }
        ]
      },
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.full",
            "pattern": "[?].*$",
            "replace": "?REDACTED",
            "action": "mask"
          }
        ]
      }
    ]
  }
}

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

export class RedactQueryStringsSample {
  static async run() {
    const { useAzureMonitor } = await import("@azure/monitor-opentelemetry");
    const { SEMATTRS_HTTP_ROUTE, SEMATTRS_HTTP_TARGET, SEMATTRS_HTTP_URL } =
      await import("@opentelemetry/semantic-conventions");

    class RedactQueryStringProcessor {
      forceFlush() { return Promise.resolve(); }
      onStart() {}
      shutdown() { return Promise.resolve(); }
      onEnd(span: any) {
        const route = String(span.attributes[SEMATTRS_HTTP_ROUTE] ?? "");
        const url = String(span.attributes[SEMATTRS_HTTP_URL] ?? "");
        const target = String(span.attributes[SEMATTRS_HTTP_TARGET] ?? "");

        const strip = (s: string) => {
          const i = s.indexOf("?");
          return i === -1 ? s : s.substring(0, i);
        };

        if (route) span.attributes[SEMATTRS_HTTP_ROUTE] = strip(route);
        if (url) span.attributes[SEMATTRS_HTTP_URL] = strip(url);
        if (target) span.attributes[SEMATTRS_HTTP_TARGET] = strip(target);
      }
    }

    const options = {
      azureMonitorExporterOptions: {
        connectionString:
          process.env.APPLICATIONINSIGHTS_CONNECTION_STRING || "<YOUR-CONNECTION-STRING>",
      },
      spanProcessors: [new RedactQueryStringProcessor()],
    };

    const monitor = useAzureMonitor(options);
    console.log("Azure Monitor initialized (query strings redacted)");
  }
}

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

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

OTEL_METRIC_EXPORT_INTERVAL=60000

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

Совет

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

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

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-12-10

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

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

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

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

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

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

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

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

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

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

Динамические метрики

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

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

Включение средства экспорта OTLP

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

Строки запроса URL-адреса Redact

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

Обратная связь

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