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

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

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

OpenTelemetry 发布状态

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

注意

有关每项功能的发布状态,请参阅常见问题解答

入门

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

先决条件

提示

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

安装客户端库

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

dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore 

启用 Azure Monitor Application Insights

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

修改你的应用程序

UseAzureMonitor() 添加到你的应用程序启动中。 可在 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 OpenTelemetry and configure it to use Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

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

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

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

提示

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

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

Screenshot that shows Application Insights overview and connection string.

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

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

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

A. 通过环境变量设置(推荐)

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

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

B. 通过配置文件设置 - 仅 Java(推荐)

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

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

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

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

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

注意

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

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

确认有数据流

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

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

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

重要

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

提示

默认情况下会启用速率为每秒 5 个请求的采样,有助于成本管理。 在超过此速率的情况下,遥测数据可能会丢失。 有关修改采样配置的详细信息,请参阅采样替代

在使用 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 上获得一流的体验。 这在 OpenTelemetry 中也称为发行版

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

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

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

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

如何测试 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,建议使用 OpenTelemetry 发行版。 只需一行代码即可开始。

对于其他所有 .NET 方案(例如经典 ASP.NET、控制台应用等),建议使用导出程序:Azure.Monitor.OpenTelemetry.Exporter

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

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

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

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。

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

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

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

请参阅 OpenTelemetry 概述

是否可以使用 OpenTelemetry 收集器?

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

OpenCensus 和 OpenTelemetry 之间有何区别?

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

疑难解答

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

支持

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

OpenTelemetry 反馈

若要提供反馈,请查看以下内容:

后续步骤