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

注意

对于.NET、Node.js和Python应用程序：

新应用或首次采用 OpenTelemetry：使用 Microsoft OpenTelemetry 发行版。
已使用 Azure Monitor OpenTelemetry 发行版：无需执行任何操作。
使用 Application Insights .NET SDK 2.x：升级到 3.x 以最大程度地减少重新插桩，或者开始使用 Microsoft OpenTelemetry Distro。

对于Java应用程序，请使用 Azure Monitor OpenTelemetry 发行版。

本指南介绍如何使用 Microsoft OpenTelemetry 发行版向应用程序添加可观测性。发行版会自动收集包含内置工具的跟踪、指标和日志，并将遥测数据导出到 Azure Monitor、任何 OpenTelemetry 协议（OTLP）终结点或 Microsoft 代理 365。

有关其他集合和导出选项，请参阅带Azure Monitor的 OpenTelemetry。

OpenTelemetry 发布状态

有关包详细信息和发行说明，请参阅后续步骤。

注意

有关 Azure 函数应用的信息，请参阅在 Azure Functions 中使用 OpenTelemetry。

使用 Application Insights 启用 OpenTelemetry

按照本部分的步骤为您的应用程序集成 OpenTelemetry 工具。选择一个用于特定语言说明的选项卡。

Microsoft OpenTelemetry 发行版包标识符和安装命令包括：

语言	Package	安装命令
Python	`microsoft-opentelemetry`	`pip install microsoft-opentelemetry`
Node.js	`@microsoft/opentelemetry`	`npm install @microsoft/opentelemetry`
.NET	`Microsoft.OpenTelemetry`	`dotnet add package Microsoft.OpenTelemetry`

对于Java，请使用Java和Java本机选项卡中所述的代理或本机映像集成。

对于 Web 应用程序，使用“ASP.NET Core”选项卡；对于控制台和其他非托管应用程序，使用“.NET”选项卡。

先决条件

Azure订阅：创建试用Azure订阅
Application Insights 资源：创建 Application Insights 资源

ASP.NET Core Application 使用正式支持的 .NET

提示

如果要从 Application Insights .NET SDK 2.x 升级，请按照 SDK 3.x 迁移指南进行操作。该升级不需要切换到 Microsoft OpenTelemetry 发行版。

安装客户端库

注意

这些安装步骤适用于使用 Microsoft OpenTelemetry 发行版的应用程序。它们不是现有 Azure Monitor OpenTelemetry 发行版用户的升级要求。不要在同一应用程序中初始化这两个发行版。独立Azure Monitor导出包保留其现有名称。

安装 Microsoft.OpenTelemetry NuGet 包：

dotnet add package Microsoft.OpenTelemetry

注意

安装 Microsoft.OpenTelemetry NuGet 包：

dotnet add package Microsoft.OpenTelemetry

注意

安装 @microsoft/opentelemetry npm 包：

npm install @microsoft/opentelemetry

注意

安装 microsoft-opentelemetry PyPI 包：

pip install microsoft-opentelemetry

修改你的应用程序

在应用程序开始处理工作之前初始化 Microsoft OpenTelemetry 发行版。以下示例选择 Azure Monitor 作为目标，并从 APPLICATIONINSIGHTS_CONNECTION_STRING 环境变量中读取连接字符串。在启动应用程序之前设置该变量，如本文稍后所述。

还可以在代码中设置连接字符串。对于 .NET，请在 UseMicrosoftOpenTelemetry() 内部使用 options.AzureMonitor.ConnectionString。有关所有支持的语言，请参阅连接字符串配置。

在Program.cs中，将应用程序生成器配置为使用 Microsoft OpenTelemetry 发行版：

// Import the distro API.
using Microsoft.OpenTelemetry;

// Create the application builder.
var builder = WebApplication.CreateBuilder(args);

// Initialize the Microsoft OpenTelemetry Distro with Azure Monitor export.
builder.UseMicrosoftOpenTelemetry(options =>
{
    options.Exporters = ExportTarget.AzureMonitor;
});

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

对于控制台和其他非托管应用程序，请在应用程序代码之前创建 OpenTelemetry SDK 实例：

// Import the distro and SDK APIs.
using Microsoft.OpenTelemetry;
using OpenTelemetry;

// Create the Microsoft OpenTelemetry Distro and keep the SDK alive until shutdown.
using var sdk = OpenTelemetrySdk.Create(telemetry =>
{
    // Select Azure Monitor as the export destination.
    telemetry.UseMicrosoftOpenTelemetry(options =>
    {
        options.Exporters = ExportTarget.AzureMonitor;
    });
});

在应用程序的生存期内保持 sdk 活动状态。仅在关闭期间调用 Dispose 释放它，以刷新挂起的遥测数据并停止提供程序。

自动仪器化是通过配置更改启用的。不需更改代码。

通过将 -javaagent:"path/to/applicationinsights-agent-3.7.9.jar" 添加到应用程序的 JVM 参数，将Java虚拟机（JVM）指向 jar 文件。

注意

默认情况下，采样的速率为每秒 5 个请求，有助于成本管理。在超出此速率的方案中，遥测数据可能缺失。有关修改采样配置的详细信息，请参阅采样替代。如果在 Application Insights 中看到意外费用或高成本，本指南将有所帮助。它涵盖了常见的原因，例如高遥测量、数据引入峰值和配置错误的采样。如果您正在解决与成本峰值、遥测数据量、采样失效、数据上限、数据摄取量高或意外计费相关的问题，这将特别有用。如需入门，请参阅对 Application Insights 中数据引入量过高的问题进行故障排除。

提示

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

提示

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

对于 CommonJS 应用程序，请在加载要插桩的库之前初始化 Microsoft OpenTelemetry 发行版：

// Import the distro API.
const { useMicrosoftOpenTelemetry } = require("@microsoft/opentelemetry");

// Initialize the distro before loading application libraries.
useMicrosoftOpenTelemetry({
    azureMonitor: {
        azureMonitorExporterOptions: {
            // Read the Azure Monitor connection string from the environment.
            connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
        },
    },
});

对于 ECMAScript 模块（ESM），请创建启动 telemetry.mjs 文件：

// Register instrumentation hooks before loading application modules.
import "@microsoft/opentelemetry/loader";
import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

// Initialize the Microsoft OpenTelemetry Distro with Azure Monitor export.
useMicrosoftOpenTelemetry({
    azureMonitor: {
        azureMonitorExporterOptions: {
            // Read the connection string from the environment.
            connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
        },
    },
});

预加载 bootstrap 文件，以便在应用程序模块加载之前注册插桩钩子：

node --import ./telemetry.mjs "<AppEntryPoint>"

使用 Microsoft OpenTelemetry 发行版启用Azure Monitor导出并选择命名的应用程序记录器。通过使用命名记录器，可以避免收集 SDK 自己的日志消息：

# Import the logging and distro APIs.
import logging
from microsoft.opentelemetry import use_microsoft_opentelemetry

# Select an application logger to avoid collecting the SDK's own logs.
loggerName = "<LoggerName>"

# Enable Azure Monitor export using the connection string environment variable.
use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    logger_name=loggerName,
)

# Collect application log records at INFO level and above.
logger = logging.getLogger(loggerName)
logger.setLevel(logging.INFO)

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

连接字符串标识接收遥测数据的 Application Insights 资源。

提示

如果你没有 Application Insights 资源，可按照该指南创建一个资源。建议创建一个新资源，而不是使用现有资源。

复制连接字符串：

转到 Application Insights 资源的“概述”窗格。
查找“连接字符串”。
将鼠标悬停在连接字符串上，然后选择Copy 到剪贴板图标。

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

若要粘贴连接字符串，请使用以下方法之一：

方法	支持的语言	建议用于
环境变量	全部	生产
配置文件（`applicationinsights.json`）	仅限 Java	生产环境（Java）
Code	.NET、Node.js、Python	仅限本地开发/测试

重要

建议仅在本地开发和测试环境下通过代码设置连接字符串。

对于生产环境，请使用环境变量或配置文件（仅Java）。

将 Application Insights 连接字符串作为环境变量（建议用于生产）

在 Bash 中：

export APPLICATIONINSIGHTS_CONNECTION_STRING="<ConnectionString>"

在 PowerShell 中：

$env:APPLICATIONINSIGHTS_CONNECTION_STRING = "<ConnectionString>"

在配置文件中设置 Application Insights 连接字符串 - 仅适用于 Java

创建包含以下内容的、名为 applicationinsights.json 的配置文件，并将其置于 applicationinsights-agent-3.7.9.jar 所在的同一目录：
```
    {
        "connectionString": "<ConnectionString>"
    }
```
- 仅限 .NET、Node.js 和 Python

有关 Microsoft OpenTelemetry 发行版选项，请参阅.NET、 Node.js或Python文档。

确认有数据流

配置发行版并设置连接字符串后，运行应用程序并生成流量或日志消息。在 Azure 门户中打开 Application Insights 资源，验证是否显示遥测数据。数据可能在数分钟后才会显示。

“Application Insights 概述”选项卡的屏幕截图，其中突出显示服务器请求和服务器响应时间。

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

注意

作为使用 Application Insights 检测的一部分，我们将收集诊断数据并将其发送到Microsoft。这些数据可帮助我们运行和改进 Application Insights。在 Application Insights 常见问题解答中了解详细信息。

重要

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

故障排除、反馈和支持

提示

以下部分适用于所有 OpenTelemetry 发行版文章。

故障排除

有关故障排除的信息，请参阅在 .NET 中排查 OpenTelemetry 问题和在 Azure Monitor Application Insights 中排查缺少的应用程序遥测问题。

OpenTelemetry 反馈

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

通过加入 OpenTelemetry 早期采用者社区来告诉Microsoft自己。
在 Microsoft Tech Community 中与其他Azure Monitor用户互动。
在 Azure 反馈论坛发出功能请求。

支持

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

对于 Azure 支持问题，请打开 Azure 支持工单。
对于 OpenTelemetry 问题，请直接联系 OpenTelemetry .NET 社区。
有关与Azure Monitor导出程序相关的开放问题列表，请参阅 GitHub 问题页。

后续步骤

若要查看源代码，请参阅适用于 .NET 的 Microsoft OpenTelemetry Distro 存储库。
若要查看示例应用程序，请参阅 Microsoft OpenTelemetry Distro for ASP.NET Core。
若要安装 NuGet 包、检查更新或查看发行说明，请参阅Microsoft.OpenTelemetry 包。
有关仍在使用Azure.Monitor.OpenTelemetry.AspNetCore的应用程序，请参阅Azure Monitor发行版文档。
若要了解有关 OpenTelemetry 及其社区的详细信息，请参阅 OpenTelemetry .NET GitHub 存储库。
要提高使用体验，请启用Web或浏览器用户监视。

若要查看源代码，请参阅适用于 .NET 的 Microsoft OpenTelemetry Distro 存储库。
有关非托管设置，请参阅为控制台应用和后台工具配置 Microsoft OpenTelemetry 发行版。
若要安装 NuGet 包、检查更新或查看发行说明，请参阅Microsoft.OpenTelemetry 包。
有关使用独立Azure.Monitor.OpenTelemetry.Exporter包的应用程序，请参阅Azure Monitor导出程序文档。
若要了解有关 OpenTelemetry 及其社区的详细信息，请参阅 OpenTelemetry .NET GitHub 存储库。
要提高使用体验，请启用Web或浏览器用户监视。

若要查看源代码，请参阅适用于 Node.js 的 Microsoft OpenTelemetry Distro 存储库。
若要查看示例应用程序，请参阅适用于 Node.js 的 Microsoft OpenTelemetry Distro 示例。
若要安装 npm 包并检查更新，请参阅 @microsoft/opentelemetry 包。
有关仍在使用@azure/monitor-opentelemetry的应用程序，请参阅Azure Monitor发行版文档。
若要了解有关 OpenTelemetry 及其社区的详细信息，请参阅 OpenTelemetry JavaScript GitHub存储库。
要提高使用体验，请启用Web或浏览器用户监视。

若要查看源代码和配置，请参阅适用于 Python 的 Microsoft OpenTelemetry Distro 存储库。
若要查看示例应用程序，请参阅适用于 Python 的 Microsoft OpenTelemetry 发行版示例。
若要安装 PyPI 包并检查更新，请参阅 microsoft-opentelemetry 包。
查看GitHub上的 release 注释。
有关仍在使用azure-monitor-opentelemetry的应用程序，请参阅Azure Monitor发行版文档。
若要查看可用的 OpenTelemetry 检测和组件，请参阅 OpenTelemetry 参与者Python GitHub存储库。
若要了解有关 OpenTelemetry 及其社区的详细信息，请查看 OpenTelemetry Python GitHub 存储库。
要提高使用体验，请启用Web或浏览器用户监视。

上次更新时间为 2026-10-23