配置 Azure Monitor OpenTelemetry

  • 项目

本文介绍 Azure Monitor OpenTelemetry 发行版的配置设置。

连接字符串

Application Insights 中的连接字符串定义发送遥测数据的目标位置，确保它到达适当的资源以进行监视和分析。

使用以下三种方法来配置连接字符串：

  • 将 UseAzureMonitor() 添加到 program.cs 类中的应用程序启动。

    // 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 => {
    options.ConnectionString = "<Your Connection String>";
});

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

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

  • 设置环境变量。

    APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

  • 将以下部分添加到 appsettings.json 配置文件。

    {
  "AzureMonitor": {
      "ConnectionString": "<Your Connection String>"
  }
}

注意

如果在多个位置设置连接字符串，我们遵循以下优先顺序：

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

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

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

通过资源属性设置云角色名称和云角色实例。 云角色名称使用 service.namespace 和 service.name 属性，但如果未设置 service.namespace，它将回滚到 service.name。 云角色实例使用 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 OpenTelemetry tracer provider to add the resource attributes to all traces.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => 
    builder.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 提供自定义固定速率采样器，该采样器使用采样率填充事件，Application Insights 会将其转换为 ItemCount。 固定速率采样器可确保准确的体验和事件计数。 采样器旨在跨服务保留跟踪，并可与较旧的 Application Insights SDK 互操作。 有关详细信息，请参阅详细了解采样。

注意

指标和日志不受采样影响。

采样器需要 0 到 1 之间（含）的采样率。 0.1 意味着会发送大约 10% 的跟踪。

// 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(o =>
{
    // Set the sampling ratio to 10%. This means that 10% of all traces will be sampled and sent to Azure Monitor.
    o.SamplingRatio = 0.1F;
});

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

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

提示

使用固定比率/百分比采样时，如果你不确定如何设置采样率，请从 5%（即 0.05 采样率）开始，并根据失败和性能边栏选项卡中显示的操作准确度调整比率。 通常情况下，采样率越高，准确度越高。 但是，任何采样都会影响准确度，因此我们建议对不受采样影响的 OpenTelemetry 指标发出警报。

启用 Microsoft Entra ID（前 Azure AD）身份验证

你可能需要启用 Microsoft Entra 身份验证，以便更安全地连接到 Azure，从而防止未经授权的遥测数据引入你的订阅。

我们支持 Azure 标识提供的凭据类。

  • 建议使用 DefaultAzureCredential 进行本地开发。
  • 建议使用 ManagedIdentityCredential 处理系统分配和用户分配的托管标识。
    • 对于系统分配的托管标识，使用不带参数的默认构造函数。
    • 对于用户分配的托管标识，请向构造函数提供客户端 ID。
  • 建议使用 ClientSecretCredential 处理服务主体。
    • 向构造函数提供租户 ID、客户端 ID 和客户端密码。

  1. 安装最新的 Azure.Identity 包：

    dotnet add package Azure.Identity

  2. 提供所需的凭据类：

    // 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 credential to the DefaultAzureCredential.
    // This credential will use the Azure identity of the current user or
    // the service principal that the application is running as to authenticate
    // to Azure Monitor.
    options.Credential = new DefaultAzureCredential();
});

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

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

脱机存储和自动重试

为了提高可靠性和复原能力，基于 OpenTelemetry 的 Azure Monitor 产品/服务默认在应用程序与 Application Insights 失去连接时写入脱机/本地存储。 这会将应用程序遥测数据保存到磁盘，并定期尝试再次发送遥测数据，最长持续时间为 48 小时。 在高负载应用程序中，遥测偶尔会出于两个原因而被删除。 首先，当允许的时间超过时；其次，当文件大小超过最大值或 SDK 没有机会清除文件时。 如果需要选择，产品会保存较新的事件，而不是较旧的事件。 了解详细信息

发行版包中包括 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 cannot 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 上的示例。

    // 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 资源属性的值。 如果 OTEL_RESOURCE_ATTRIBUTES 中也提供了 service.name，则 OTEL_SERVICE_NAME 优先。

常见问题

本部分提供常见问题的解答。

什么是 OpenTelemetry？

它是一种新的可观测性开源标准。 有关详细信息，请参阅 OpenTelemetry。

Azure Monitor 为什么要对 OpenTelemetry 进行投资？

Microsoft 是 OpenTelemetry 的最大贡献者之一。

OpenTelemetry 的关键价值主张是，它与供应商无关，可以跨语言提供一致的 API/SDK。

随着时间的推移，我们相信 OpenTelemetry 将使 Azure Monitor 客户能够观察用我们支持的语言之外的语言编写的应用程序。 它还通过丰富的检测库扩展了你可以收集的数据类型。 此外，OpenTelemetry SDK 在大规模使用时往往比其前身 Application Insights SDK 的性能更高。

最后，OpenTelemetry 符合 Microsoft 的拥抱开源策略。

OpenTelemetry 的状态是什么？

请参阅 OpenTelemetry 状态。

什么是“Azure Monitor OpenTelemetry 发行版”？

你可以将其视为一个精简包装器，它将所有 OpenTelemetry 组件捆绑在一起，以便在 Azure 上获得一流的体验。 此包装器也称为 OpenTelemetry 中的分发。

我为什么应该使用“Azure Monitor OpenTelemetry 发行版”？

使用 Azure Monitor OpenTelemetry 发行版相比于社区原生的 OpenTelemetry 有几个优势：

本着 OpenTelemetry 的精神，我们设计的发行版具有开放性和可扩展性。 例如，你可以添加：

  • OpenTelemetry 协议(OTLP) 导出程序，同时发送到第二个目标
  • 发行版中未包含的其他检测库

由于 Distro 提供 OpenTelemetry 分发，因此 Distro 支持 OpenTelemetry 所支持的任何功能。 例如，你可以添加更多遥测处理器、导出程序或检测库（如果受 OpenTelemetry 支持）。

注意

Distro 将采样器设置为 Application Insights 的自定义固定比率采样器。 你可以将其更改为不同的采样器，但这样做可能会禁用 Distro 包含的某些功能。 有关支持的采样器的详细信息，请参阅配置 Azure Monitor OpenTelemetry 的启用采样部分。

对于没有受支持独立 OpenTelemetry 导出程序的语言，目前仅支持通过 Azure Monitor OpenTelemetry Distro 方式将 OpenTelemetry 与 Azure Monitor 配合使用。 对于具有受支持独立 OpenTelemetry 导出程序的语言，可以根据遥测方案选择使用 Azure Monitor OpenTelemetry Distro 或相应的独立 OpenTelemetry 导出程序。 有关详细信息，请参阅何时应使用 Azure Monitor OpenTelemetry 导出程序？。

如何测试 Azure Monitor OpenTelemetry 发行版？

请查看我们的 .NET、Java、JavaScript (Node.js) 和 Python 启用文档。

我应该使用 OpenTelemetry 还是 Application Insights SDK？

除非所需功能仅通过 Application Insights SDK 的正式支持提供，否则建议使用 OpenTelemetry 发行版。

立即采用 OpenTelemetry，可避免以后再迁移。

何时使用 Azure Monitor OpenTelemetry 导出程序？

对于 ASP.NET Core、Java、Node.js 和 Python，建议使用 Azure Monitor OpenTelemetry Distro。 只需一行代码即可开始。

对于所有其他 .NET 方案（包括经典 ASP.NET、控制台应用等），建议使用 .NET Azure Monitor OpenTelemetry 导出程序：Azure.Monitor.OpenTelemetry.Exporter。

对于需要高级配置的更复杂的 Python 遥测方案，我们建议使用 Python Azure Monitor OpenTelemetry 导出程序。

Azure Monitor OpenTelemetry 发行版中功能的当前发布状态是什么？

以下图表划分了每种语言的 OpenTelemetry 功能支持。

Feature .NET Node.js Python Java
分布式跟踪 ✅ ✅ ✅ ✅
自定义指标 ✅ ✅ ✅ ✅
标准指标（准确性当前受采样影响） ✅ ✅ ✅ ✅
固定速率采样 ✅ ✅ ✅ ✅
脱机存储和自动重试 ✅ ✅ ✅ ✅
异常报告 ✅ ✅ ✅ ✅
日志收集 ✅ ⚠️ ✅ ✅
自定义事件 ⚠️ ⚠️ ⚠️ ✅
实时指标 ❌ ❌ ❌ ✅
检测 VM/VMSS 和应用程序服务的资源上下文 ✅ ❌ ✅ ✅
检测 AKS 和 Functions 的资源上下文 ❌ ❌ ❌ ✅
可用性测试范围筛选 ❌ ❌ ❌ ✅
自动填充用户 ID、经过身份验证的用户 ID 和用户 IP ❌ ❌ ❌ ✅
手动覆盖/设置操作名称、用户 ID 或经过身份验证的用户 ID ❌ ❌ ❌ ✅
自适应采样 ❌ ❌ ❌ ✅
探查器 ❌ ❌ ❌ ⚠️
快照调试程序 ❌ ❌ ❌ ❌

键

  • ✅ 此功能适用于享受正式支持的所有客户。
  • ⚠ 此功能目前以公共预览版提供。 请参阅 Azure 预览版补充使用条款。
  • ❌ 此功能不可用或不适用。

OpenTelemetry 能否用于 Web 浏览器？

可以，但我们不建议使用它，Azure 不支持它。 OpenTelemetry JavaScript 针对 Node.js 进行了深度优化。 相反，我们建议使用 Application Insights JavaScript SDK。

何时可以在 Web 浏览器中使用 OpenTelemetry SDK？

OpenTelemetry Web SDK 没有确定的可用性时间线。 我们可能还需要几年的时间，才能开发出可以替代 Application Insights JavaScript SDK 的浏览器 SDK。

今天能否在 Web 浏览器中测试 OpenTelemetry？

OpenTelemetry Web 沙盒 是一个分支，旨在使 OpenTelemetry 在浏览器中运行。 目前无法将遥测数据发送到 Application Insights。 SDK 不定义常规客户端事件。

是否支持将 Application Insights 与 AppDynamics、DataDog 和 NewRelic 等竞争对手代理一起运行？

不是。 我们不打算为此类问题提供测试或支持，不过，我们的发行版允许同时导出到 OTLP 终结点和 Azure Monitor。

是否可以在生产环境中使用预览功能？

但我们不建议这样做。 请参阅 Azure 预览版补充使用条款。

手动和自动检测之间有何区别？

请参阅 OpenTelemetry 概述。

是否可以使用 OpenTelemetry 收集器？

某些客户使用 OpenTelemetry-Collector 作为代理替代方案，尽管 Microsoft 尚不正式支持使用基于代理的方法进行应用程序监视。 与此同时，开源社区贡献了一个 OpenTelemetry-Collector Azure Monitor 导出器，某些客户正在使用它向 Azure Monitor Application Insights 发送数据。 Microsoft 对此不支持。

OpenCensus 和 OpenTelemetry 之间有何区别？

OpenCensus 是 OpenTelemetry 的前身。 Microsoft 帮助整合 OpenTracing 和 OpenCensus 用于创建 OpenTelemetry，OpenTelemetry 是全球唯一的可观测性标准。 Azure Monitor 当前生产推荐的 Python SDK 基于 OpenCensus。 Microsoft 致力于基于 OpenTelemetry 创建 Azure Monitor。

疑难解答

不起作用？ 查看 ASP.NET Core 的故障排除页面。

支持

选择所选语言的选项卡，以发现支持选项。

OpenTelemetry 反馈

若要提供反馈，请查看以下内容：