你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

为 .NET、Node.js、Python 和 Java 应用程序启用 Azure Monitor OpenTelemetry

项目
10/30/2023

本文介绍如何启用和配置基于 OpenTelemetry 的数据收集，以便为 Azure Monitor Application Insights 中的体验提供支持。我们会逐步介绍如何安装“Azure Monitor OpenTelemetry 发行版”。该发行版会自动收集应用程序及其依赖项的跟踪、指标、日志和异常。若要详细了解如何使用 OpenTelemetry 收集数据，请参阅数据收集基础知识或 OpenTelemetry 常见问题解答。

OpenTelemetry 发布状态

OpenTelemetry 产品/服务适用于 .NET、Node.js、Python 和 Java 应用程序。

语言	版本状态
.NET（导出程序）	✅ ¹
Java	✅ ¹
Node.js	✅ ¹
Python	✅ ¹
ASP.NET Core	⚠️ ²

脚注

✅：OpenTelemetry 适用于享受正式支持的所有客户。
⚠：OpenTelemetry 以公共预览版形式提供。 Microsoft Azure 预览版补充使用条款

注意

有关每项功能的发布状态，请参阅常见问题解答。在正式发布之前，ASP.NET Core 发行版将接受其他稳定性测试。如果需要为 ASP.NET Core 应用程序提供完全受支持的 OpenTelemetry 解决方案，则可以使用 .NET 导出程序。

开始使用

遵循本部分提供的步骤使用 OpenTelemetry 检测应用程序。

先决条件

一个 Azure 订阅：免费创建 Azure 订阅
一个 Application Insights 资源：创建 Application Insights 资源

使用官方支持版本 .NET Core 的 ASP.NET Core 应用程序

提示

不建议将 OTel 社区 SDK/API 与 Azure Monitor OTel 发行版配合使用，因为它会自动将它们作为依赖项加载。

安装客户端库

安装最新的 Azure.Monitor.OpenTelemetry.AspNetCore NuGet 包：

dotnet add package --prerelease Azure.Monitor.OpenTelemetry.AspNetCore

安装最新的 Azure.Monitor.OpenTelemetry.Exporter NuGet 包：

dotnet add package Azure.Monitor.OpenTelemetry.Exporter

要安装这些包：

@azure/monitor-opentelemetry

npm install @azure/monitor-opentelemetry

以下包还可用于本文稍后介绍的一些特定方案：

npm install @opentelemetry/api
npm install @opentelemetry/sdk-metrics
npm install @opentelemetry/resources
npm install @opentelemetry/semantic-conventions
npm install @opentelemetry/sdk-trace-base

安装最新的 azure-monitor-opentelemetry PyPI 包：

pip install azure-monitor-opentelemetry

启用 Azure Monitor Application Insights

若要启用 Azure Monitor Application Insights，需对应用程序进行少量修改，并设置“连接字符串”。连接字符串会告知应用程序应将发行版收集的遥测数据发送到何处，该数据对你来说是独一无二的。

修改你的应用程序

将 UseAzureMonitor() 添加到你的应用程序启动中。根据你的 .NET 的版本，它在你的 startup.cs 或 program.cs 类中。

// Import the Azure.Monitor.OpenTelemetry.AspNetCore namespace.
using Azure.Monitor.OpenTelemetry.AspNetCore;

// Create a new WebApplicationBuilder instance.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry NuGet package to the application's services and configure OpenTelemetry to use Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the application.
var app = builder.Build();

// Run the application.
app.Run();

在应用程序启动时，将 Azure Monitor 添加到每个 OpenTelemetry 信号中。根据你的 .NET 的版本，它在你的 startup.cs 或 program.cs 类中。

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

// Add an Azure Monitor metric exporter to the metrics provider builder.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter();

// 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(options =>
    {
        options.AddAzureMonitorLogExporter();
    });
});

注意

有关详细信息，请参阅 OpenTelemetry .NET 入门教程

Java 自动检测通过配置更改启用，无需更改代码。

通过将 -javaagent:"path/to/applicationinsights-agent-3.4.18.jar" 添加到应用程序的 JVM 参数，使 JVM 指向 jar 文件。

提示

有关特定于场景的指南，请参阅入门（补充）。

提示

如果你要开发 Spring Boot 应用程序，可以选择性地使用编程配置替换 JVM 参数。有关详细信息，请参阅将 Azure Monitor Application Insights 与 Spring Boot 配合使用。

// Import the `useAzureMonitor()` function from the `@azure/monitor-opentelemetry` package.
const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

// Call the `useAzureMonitor()` function to configure OpenTelemetry to use Azure Monitor.
useAzureMonitor();

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

# Import the tracing api from the `opentelemetry` package.
from opentelemetry import trace

# Configure OpenTelemetry to use Azure Monitor with the specified connection
# string.
configure_azure_monitor(
    connection_string="<Your Connection String>",
)

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

# Start a new span with the name "hello". This also sets this created span as the current span in this context. This span will be exported to Azure Monitor as part of the trace.
with tracer.start_as_current_span("hello"):
    print("Hello, World!")

# Wait for export to take place in the background.
input()

从 Application Insights 资源复制连接字符串

提示

如果你还没有资源，现在是创建 Application Insights 资源的绝佳时机。建议在以下情况下创建新的 Application Insights 资源，而不是使用现有资源。

若要复制你唯一的连接字符串：

转到 Application Insights 资源的“概述”窗格。
查找你的连接字符串。
将鼠标指针悬停在连接字符串上，并选择“复制到剪贴板”图标。

将连接字符串粘贴到你的环境中

要粘贴连接字符串，请从以下选项中进行选择：

A. 通过环境变量设置（推荐）

将以下命令中的 <Your Connection String> 替换为你的唯一连接字符串。

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

B. 通过配置文件设置 - 仅 Java（推荐）

创建包含以下内容的、名为 applicationinsights.json 的配置文件，并将其置于 applicationinsights-agent-3.4.18.jar 所在的同一目录：

{
  "connectionString": "<Your Connection String>"
}

将之前的 JSON 中的 <Your Connection String> 替换为你的唯一连接字符串。

C. 通过代码设置 - ASP.NET Core、Node.js 和 Python（不推荐）

有关通过代码设置连接字符串的示例，请参阅连接字符串配置。

注意

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

代码
环境变量
配置文件

确认有数据流

运行应用程序，然后打开 Azure 门户中的“Application Insights 资源”选项卡。数据可能在数分钟后才会显示在门户中。

Screenshot of the Application Insights Overview tab with server requests and server response time highlighted.

你现在已为应用程序启用 Application Insights。以下所有步骤都是可选的，并允许进一步自定义。

重要

如果有两个或更多服务向同一 Application Insights 资源发出遥测数据，则需要设置云角色名称以在应用程序映射中正确表示这些服务。

在使用 Application Insights 检测的过程中，我们会收集诊断数据并将其发送给 Microsoft。这些数据可帮助我们运行和改进 Application Insights。若要了解更多信息，请参阅 Azure Application Insights 中的 Statsbeat。

常见问题

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

什么是 OpenTelemetry？

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

Microsoft 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 上获得一流的体验。

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

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

减少启用工作量
受 Microsoft 支持
引入 Azure 特定功能，例如：
- 使用 Application Insights SDK 保留服务组件的跟踪
- Microsoft Entra 身份验证
- 脱机存储和自动重试
- Statsbeat
- Application Insights 标准指标
- 检测资源元数据以自动填充 Azure 上的云角色名称
- 实时指标（未来）

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

OTLP 导出程序并同时发送到第二个目标
包中捆绑内容之外的社区检测库

如何测试 Azure Monitor OpenTelemetry 发行版？

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

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

视情况而定。考虑到 Azure Monitor OpenTelemetry 发行版仍为“预览版”，并且它并未完全与 Application Insights SDK 实现功能奇偶一致性。

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

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

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

键

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

OpenTelemetry 能否用于 Web 浏览器？

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

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

OpenTelemetry Web SDK 的可用性时间线尚未确定。我们可能还需要几年才会推出一款浏览器 SDK 来用作 Application Insights JavaScript SDK 的可行替代项。

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

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

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

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

我是否可以在生产环境中使用预览版？

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

是否可以将 Azure Monitor 导出程序用作独立组件？

是，我们了解一些客户可能希望使用“零碎方法”进行检测。但是，发行版提供了在 Azure 上获得最佳入门体验的最简单方法。

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

请参阅 OpenTelemetry 概述。

是否可以使用 OpenTelemetry 收集器？

某些客户已开始使用 OpenTelemetry 收集器作为代理替代项，即使 Microsoft 尚未正式支持基于代理的应用程序监视方法。与此同时，开源社区提供了 OpenTelemetry 收集器 Azure Monitor 导出程序，一些客户正在使用该导出程序将数据发送到 Azure Monitor Application Insights。

我们计划在将来支持基于代理的方法，但详细信息和时间线尚不可用。我们的目标是通过 OpenTelemetry 协议 (OTLP) 为 OpenTelemetry 支持的任何语言提供发送到 Azure Monitor 的路径。此方法使客户能够观察用我们支持的语言之外的语言编写的应用程序。

OpenCensus 和 OpenTelemetry 之间有何区别？

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

疑难解答

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

支持

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

有关 Azure 支持问题，可打开 Azure 支持票证。
有关 OpenTelemetry 问题，请直接与 OpenTelemetry .NET 社区联系。
有关与 Azure Monitor 导出程序相关的未解决问题列表，请参阅 GitHub 问题页。

OpenTelemetry 反馈

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

填写 OpenTelemetry 社区的客户反馈调查。
加入 OpenTelemetry 早期采用者社区，告诉 Microsoft 有关你本人的信息。
在 Microsoft 技术社区与其他 Azure Monitor 用户联系。
在 Azure 反馈论坛中发出功能请求。

后续步骤

有关添加和修改 Azure Monitor OpenTelemetry 的详细信息，请参阅添加和修改 Azure Monitor OpenTelemetry
若要进一步配置 OpenTelemetry 发行版，请参阅 Azure Monitor OpenTelemetry 配置
若要查看源代码，请参阅 Azure Monitor AspNetCore GitHub 存储库。
若要安装 NuGet 包、检查更新或查看发行说明，请参阅 Azure Monitor AspNetCore NuGet 包页面。
若要进一步了解 Azure Monitor 和 OpenTelemetry，请参阅 Azure Monitor 示例应用程序。
若要详细了解 OpenTelemetry 及其社区，请参阅 OpenTelemetry .NET GitHub 存储库。
若要开启使用体验，请参阅启用 Web 或浏览器用户监视。

有关添加和修改 Azure Monitor OpenTelemetry 的详细信息，请参阅添加和修改 Azure Monitor OpenTelemetry
要查看源代码，请参阅 Azure Monitor OpenTelemetry GitHub 存储库。
若要安装 npm 包并检查更新，请参阅 @azure/monitor-opentelemetry npm 包页面。
若要进一步了解 Azure Monitor Application Insights 和 OpenTelemetry，请参阅 Azure Monitor 示例应用程序。
若要详细了解 OpenTelemetry 及其社区，请参阅 OpenTelemetry JavaScript GitHub 存储库。
若要开启使用体验，请参阅启用 Web 或浏览器用户监视。