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

OpenTelemetry 帮助、支持和反馈

本文提供适用于 .NET、Java、Node.js 和 Python 应用的 Azure Monitor Application Insights 上的 OpenTelemetry 帮助、支持和反馈选项。

• 查看常见问题解答
• 采取故障排除步骤
• 获取支持
• 提供反馈

常见问题解答

什么是 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 有几个优势：

• 减少启用工作量
• 受 Microsoft 支持
• 引入 Azure 特定的功能，例如：
  • 与经典 Application Insights SDK 兼容的采样
  • Microsoft Entra 身份验证
  • 脱机存储和自动重试
  • Statsbeat
  • Application Insights 标准指标
  • 检测资源元数据，以在各种 Azure 环境中自动填充云角色名称和云角色实例
  • 实时指标

本着 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、控制台应用、Windows 窗体 (WinForms) 等），建议使用 .NET Azure Monitor OpenTelemetry 导出程序：Azure.Monitor.OpenTelemetry.Exporter。

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

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

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

Feature	.NET	Node.js	Python	Java
分布式跟踪	✅	✅	✅	✅
自定义指标	✅	✅	✅	✅
标准指标	✅	✅	✅	✅
固定速率采样	✅	✅	✅	✅
脱机存储和自动重试	✅	✅	✅	✅
异常报告	✅	✅	✅	✅
日志收集	✅	⚠️	✅	✅
自定义事件	⚠️	⚠️	⚠️	✅
Microsoft Entra 身份验证	✅	✅	✅	✅
实时指标	✅	✅	✅	✅
实时指标筛选	✅	❌	❌	❌
检测 VM/VMSS 和应用程序服务的资源上下文	✅	❌	✅	✅
检测 Azure Kubernetes 服务 (AKS) 和 Functions 的资源上下文	❌	❌	❌	✅
使用跟踪可用性 API 生成的可用性测试事件	❌	❌	❌	✅
按匿名用户 ID 和综合源筛选请求、依赖项、日志和异常	❌	❌	❌	✅
按操作名称筛选依赖项、日志和异常	❌	❌	❌	✅
自适应采样	❌	❌	❌	✅
探查器	❌	❌	❌	⚠️
快照调试程序	❌	❌	❌	❌

键

• ✅ 此功能适用于享受正式支持的所有客户。
• ⚠ 此功能目前以公共预览版提供。 请参阅 Microsoft 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。

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

但我们不建议这样做。 请参阅 Microsoft 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。

Grafana 中为何会出现 Status: 500. Can't visualize trace events using the trace visualizer？

你可能正在尝试可视化原始文本日志而不是 OpenTelemetry 跟踪。

在 Application Insights 中，“跟踪”表存储的是用于诊断目的的原始文本日志。 这些日志用于帮助识别和关联与用户请求、其他事件和异常报告关联的跟踪。 但是，“跟踪”表不会直接影响 Grafana 等可视化工具中的端到端事务视图（瀑布图）。

随着云原生实践的日益普及，遥测数据收集和术语也在不断演变。 OpenTelemetry 已成为收集和检测遥测数据的标准。 在这种背景下，“跟踪”一词有了新的含义。 OpenTelemetry 中的“跟踪”并非原始日志，而是一种更丰富的、结构化形式的遥测数据，其中包括代表单个工作单位的范围。 这些范围对于构造详细事务视图至关重要，让你可以更好地监视和诊断云原生应用程序。

故障排除

ASP.NET Core

第 1 步：启用诊断日志记录

Azure Monitor 导出程序使用 EventSource 执行其内部日志记录。 通过选择加入名为OpenTelemetry-AzureMonitor-Exporter 的来源，任何 EventListener 都可以使用导出程序日志。 有关故障排除步骤，请参阅 GitHub 上的 OpenTelemetry 故障排除。

第 2 步：测试应用程序主机与引入服务的连接

Application Insights 软件开发工具包 (SDK) 和代理发送遥测，在引入终结点将其作为 REST 调用引入。 请使用 PowerShell 中的 cURL 命令或原始 REST 请求，测试从 Web 服务器或应用程序主计算机到引入服务终结点的连接。 有关更多信息，请参阅排查 Azure Monitor Application Insights 中缺失应用程序遥测的问题。

已知问题

Azure Monitor OpenTelemetry 导出程序存在以下已知问题：

• 依赖项遥测中缺少操作名称。 缺少的操作名称会导致失败，并对性能选项卡体验产生负面影响。

• 请求和依赖项遥测数据中缺少设备模型。 缺少的设备模型会对设备队列分析产生负面影响。

.NET

第 1 步：启用诊断日志记录

Azure Monitor 导出程序使用 EventSource 执行其内部日志记录。 通过选择加入名为OpenTelemetry-AzureMonitor-Exporter 的来源，任何 EventListener 都可以使用导出程序日志。 有关故障排除步骤，请参阅 GitHub 上的 OpenTelemetry 故障排除。

第 2 步：测试应用程序主机与引入服务的连接

Application Insights SDK 和代理发送遥测，在引入终结点将其作为 REST 调用引入。 请使用 PowerShell 中的 cURL 命令或原始 REST 请求，测试从 Web 服务器或应用程序主计算机到引入服务终结点的连接。 有关更多信息，请参阅排查 Azure Monitor Application Insights 中缺失应用程序遥测的问题。

已知问题

Azure Monitor OpenTelemetry 导出程序存在以下已知问题：

• 依赖项遥测中缺少操作名称。 缺少的操作名称会导致失败，并对性能选项卡体验产生负面影响。

• 请求和依赖项遥测数据中缺少设备模型。 缺少的设备模型会对设备队列分析产生负面影响。

Java

第 1 步：启用诊断日志记录

默认情况下，会在 Azure Monitor Application Insights 中启用诊断日志记录。 有关更多信息，请参阅故障排除指南：适用于 Java 的 Azure Monitor Application Insights。

第 2 步：测试应用程序主机与引入服务的连接

Application Insights SDK 和代理发送遥测，在引入终结点将其作为 REST 调用引入。 请使用 PowerShell 中的 cURL 命令或原始 REST 请求，测试从 Web 服务器或应用程序主计算机到引入服务终结点的连接。 有关更多信息，请参阅排查 Azure Monitor Application Insights 中缺失应用程序遥测的问题。

已知问题

• 如果从浏览器下载 Application Insights 客户端库进行安装，有时下载的 JAR 文件会损坏，并且大约是源文件大小的一半。 如果遇到此问题，请通过运行 curl 或 wget 命令下载 JAR 文件，如以下示例命令调用中所示：

  curl --location --output applicationinsights-agent-3.6.2.jar https://github.com/microsoft/ApplicationInsights-Java/releases/download//applicationinsights-agent-3.6.2.jar
  

  wget --output-document=applicationinsights-agent-3.6.2.jar https://github.com/microsoft/ApplicationInsights-Java/releases/download//applicationinsights-agent-3.6.2.jar
  

  注意

  示例命令调用适用于适合 Java 版本 3.4.11 的 Application Insights。 若要查找适用于 Java 的 Application Insights 当前版本的版本号和 URL 地址，请参阅 https://github.com/microsoft/ApplicationInsights-Java/releases。

Java native

以下步骤适用于 Spring Boot 本机应用程序。

第 1 步：验证 OpenTelemetry 版本

在应用程序启动期间，你可能会看到以下消息：

WARN  c.a.m.a.s.OpenTelemetryVersionCheckRunner - The OpenTelemetry version is not compatible with the spring-cloud-azure-starter-monitor dependency.
The OpenTelemetry version should be <version>

在这种情况下，必须按照 Spring Boot 入门中的 OpenTelemetry 文档导入 OpenTelemetry 物料清单。

第 2 步：启用自我诊断

如果某些内容无法按预期工作，则可以在 DEBUG 级别启用自我诊断，获取一些相关见解。 为此，请使用 APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_LEVEL 环境变量，将自我诊断级别设置为 ERROR、WARN、INFO、DEBUG 或 TRACE。

若要在运行 Docker 容器时在 DEBUG 级别启用自我诊断，请运行以下命令：

docker run -e APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_LEVEL=DEBUG <image-name>

注意

将 <image-name> 替换为相应 Docker 映像名称。

第三方信息免责声明

Microsoft 对这些独立的第三方产品的性能和可靠性不作任何明示或默示担保。

Node.js

第 1 步：启用诊断日志记录

Azure Monitor 导出程序将 OpenTelemetry API 记录器用于内部日志。 若要启用记录器，请运行以下代码片段：

const { diag, DiagConsoleLogger, DiagLogLevel } = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");

const provider = new NodeTracerProvider();
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ALL);
provider.register();

第 2 步：测试应用程序主机与引入服务的连接

Application Insights SDK 和代理发送遥测，在引入终结点将其作为 REST 调用引入。 请使用 PowerShell 中的 cURL 命令或原始 REST 请求，测试从 Web 服务器或应用程序主计算机到引入服务终结点的连接。 有关更多信息，请参阅排查 Azure Monitor Application Insights 中缺失应用程序遥测的问题。

已知问题

Azure Monitor OpenTelemetry 导出程序存在以下已知问题：

• 依赖项遥测中缺少操作名称。 缺少的操作名称会导致失败，并对性能选项卡体验产生负面影响。

• 请求和依赖项遥测数据中缺少设备模型。 缺少的设备模型会对设备队列分析产生负面影响。

• 依赖项名称中缺少数据库服务器名称。 由于不包括数据库服务器名称，OpenTelemetry 导出程序错误地将具有相同名称的表聚合到不同的服务器上。

Python

启用诊断日志记录

Microsoft Azure Monitor 导出程序使用 Python 标准日志记录库执行其内部日志记录。 针对不规则活动，OpenTelemetry API 和 Azure Monitor 导出程序日志获配严重性级别 WARNING 或 ERROR。 INFO 严重性级别用于常规活动或成功活动。

默认情况下，Python 日志记录库将严重性级别设置为 WARNING。 因此，必须更改严重性级别才能查看此严重性设置下的日志。 以下示例代码演示如何将所有严重性级别的日志输出到控制台和文件：

...
import logging

logging.basicConfig(format = "%(asctime)s:%(levelname)s:%(message)s", level = logging.DEBUG)

logger = logging.getLogger(__name__)
file = logging.FileHandler("example.log")
stream = logging.StreamHandler()
logger.addHandler(file)
logger.addHandler(stream)
...

测试应用程序主机与引入服务之间的连接性

Application Insights SDK 和代理发送遥测，在引入终结点将其作为 REST 调用引入。 请使用 PowerShell 中的 cURL 命令或原始 REST 请求，测试从 Web 服务器或应用程序主计算机到引入服务终结点的连接。 有关更多信息，请参阅排查 Azure Monitor Application Insights 中缺失应用程序遥测的问题。

避免重复遥测

如果创建多个处理器或导出程序实例，则通常会造成重复遥测。 请确保每次只针对每个遥测要素（日志、指标和分布式跟踪）运行一个导出程序和处理器。

以下部分介绍可能导致重复遥测的情况。

Azure Functions 中的重复跟踪日志

如果在 Application Insights 中看到每个跟踪日志的一对条目，则可能已启用以下类型的日志记录检测：

• Azure Functions 中的本机日志记录检测
• 分发中的 azure-monitor-opentelemetry 日志记录检测

若要防止重复，可以禁用分发的日志记录，但在 Azure Functions 中保留本机日志记录检测。 若要实现此目标，请将 OTEL_LOGS_EXPORTER 环境变量设置为 None。

“始终可用的”Azure Functions 中的重复遥测数据

如果 Azure Functions 中的“始终可用”设置为“启用”，则 Azure Functions 会在每次运行完成后在后台保持运行一些进程。 例如，假设你有一个每次调用 configure_azure_monitor 的五分钟计时器函数。 20 分钟后，可能会有四个同时运行的指标导出程序。 这种情况可能是重复指标遥测数据的来源。

在这种情况下，请将“始终可用”设置为“关闭”，或尝试在每个 configure_azure_monitor 调用之间手动关闭提供程序。 若要关闭每个提供程序，请针对每个当前计量、跟踪器和记录器提供程序运行关闭调用，如以下代码所示：

get_meter_provider().shutdown()
get_tracer_provider().shutdown()
get_logger_provider().shutdown()

Azure 工作簿和 Jupyter Notebook

Azure 工作簿和 Jupyter Notebook 可能会使导出程序进程在后台运行。 若要防止重复遥测，请在调用更多 configure_azure_monitor 之前清除缓存。

缺少来自 FastAPI 或 Flask 应用的请求遥测数据

如果缺少请求表数据但没有缺少其他类别，则可能是未检测 http 框架。 如果未正确构建 import 声明，则使用适用于 Python 的 Azure Monitor OpenTelemetry Distro 客户端库的 FastAPI 和 Flask 应用中可能会出现这种情况。 在调用 configure_azure_monitor 函数来检测 FastAPI 和 Flask 库之前，可能会分别导入 fastapi.FastAPI 或 flask.Flask。 例如，以下代码未成功检测 FastAPI 和 Flask 应用：

# FastAPI

from azure.monitor.opentelemetry import configure_azure_monitor
from fastapi import FastAPI

configure_azure_monitor()

app = FastAPI()

# Flask

from azure.monitor.opentelemetry import configure_azure_monitor
from flask import Flask

configure_azure_monitor()

app = Flask(__name__)

相反，我们建议将 fastapi 或 flask 模块作为一个整体导入，然后在访问 fastapi.FastAPI 或 flask.Flask 之前调用 configure_azure_monitor 来将 OpenTelemetry 配置为使用 Azure Monitor：

# FastAPI

from azure.monitor.opentelemetry import configure_azure_monitor
import fastapi

configure_azure_monitor()

app = fastapi.FastAPI(__name__)

# Flask

from azure.monitor.opentelemetry import configure_azure_monitor
import flask

configure_azure_monitor()

app = flask.Flask(__name__)

或者，可以在导入 fastapi.FastAPI 或 flask.Flask 之前调用 configure_azure_monitor：

# FastAPI

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

from fastapi import FastAPI

app = FastAPI(__name__)

# Flask

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

from flask import Flask

app = Flask(__name__)

支持

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

ASP.NET Core

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

.NET

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

Java

• 有关 Azure 支持问题，可打开 Azure 支持票证。
• 有关疑难解答的帮助，请参阅疑难解答步骤。
• 有关 OpenTelemetry 问题，请直接与 OpenTelemetry 社区联系。
• 有关与 Azure Monitor Java 自动检测相关的未解决问题列表，请参阅 GitHub 问题页。

Java native

• 有关 Azure 支持问题，可打开 Azure 支持票证。
• 有关 OpenTelemetry 问题，请直接与 OpenTelemetry 社区联系。
• 有关 Spring Boot 本机应用程序的开放问题列表，请参阅 GitHub 问题页面。
• 有关 Quarkus 本机应用程序的待解决问题列表，请参阅 GitHub 问题页。

Node.js

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

Python

• 有关 Azure 支持问题，可打开 Azure 支持票证。
• 有关 OpenTelemetry 问题，请直接与 OpenTelemetry Python 社区联系。
• 有关与 Azure Monitor Distro 相关的未解决问题列表，请参阅 GitHub 问题页。

OpenTelemetry 反馈

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

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