Compartilhar via

配置 Azure Monitor OpenTelemetry

本指南介绍如何使用 Azure Monitor OpenTelemetry 发行版在 Azure Monitor Application Insights 中配置 OpenTelemetry（OTel）。 正确配置可确保跨.NET、Java、Node.js和Python应用程序收集一致的遥测数据收集，从而实现更可靠的监视和诊断。

注意

有关 Azure 函数应用程序，请参阅 在 Azure Functions 中使用 OpenTelemetry。

连接字符串

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

注意

如果在多个位置设置connection string，我们遵循以下优先级：

  1. Code
  2. 环境变量
  3. 配置文件

设置云角色名称和云角色实例

对于 受支持的语言，Azure Monitor OpenTelemetry 发行版会自动检测资源上下文，并为组件的 云角色名称和云角色实例属性提供默认值。 但是，可能需要将默认值替代为对团队有意义的值。 云角色名称值以节点下面的名称出现在应用程序映射上。

通过资源属性设置云角色名称和云角色实例。 云角色名称使用 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的 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 — 采样器参数

    • 对于 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。

提示

使用固定百分比采样时，如果不确定该将采样率设置为多少，可以从 5% （0.05） 开始。 根据故障和性能窗格中所示操作的准确性来调整速率。 任何采样都降低了准确性，因此我们建议对 OpenTelemetry 指标发出警报，这些指标不受采样影响。

为日志配置基于跟踪的采样

启用后，将删除属于 未采样跟踪的 日志记录，以便日志与跟踪采样保持一致。

  • 日志记录在具有有效SpanId时被视为跟踪的一部分。
  • 如果关联的跟踪 TraceFlags 指示 未采样，则会 删除日志记录。
  • 不含任何跟踪上下文的日志记录不会受到影响。
  • 此功能默认处于启用状态。

使用以下设置配置基于跟踪的日志采样：

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

实时指标

实时指标提供实时分析仪表板，用于深入了解应用程序活动和性能。

重要

有关适用于 beta 版、预览版或尚未正式发布的 Azure 功能的法律条款，请参阅 Azure 预览补充使用条款。

此功能默认启用。

配置发行版时，用户可以禁用实时指标。

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

脱机存储和自动重试

Azure Monitor 基于 OpenTelemetry 的产品在应用程序与 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 导出器。 我们并未正式支持 OTLP 导出器或其下游的任何组件和第三方服务。

  1. 在你的项目中安装 OpenTelemetry.Exporter.OpenTelemetryProtocol 包。

    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

  2. 添加以下代码片段。 此示例假设你已经安装了一个 OpenTelemetry 收集器，并且其中正在运行一个 OTLP 接收器。 有关详细信息，请参阅 GitHub 上的 example。

    // 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 配置

使用 Azure Monitor OpenTelemetry 发行版时，通过环境变量可以访问以下 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 查询字符串，请禁用查询字符串收集。 如果使用 SAS 令牌调用Azure存储，则建议使用此设置。

使用 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 秒）。 此设置控制 OpenTelemetry SDK 导出指标的频率。

提示

Azure Monitor指标和Azure Monitor工作区以固定的 60 秒间隔引入自定义指标。 更频繁发送的指标会被缓冲，并每隔 60 秒处理一次。 Log Analytics按发送的时间间隔记录指标。较短的发送间隔可能会增加成本，而较长的间隔可能会导致可见性延迟。

有关参考，请参阅以下 OpenTelemetry 规范：

  • Last updated on