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

项目
11/11/2024

本文介绍了如何在 Application Insights 内启用和配置基于 OpenTelemetry 的数据收集。 Azure Monitor OpenTelemetry 发行版：

提供 OpenTelemetry 发行版，其中包括对特定于 Azure Monitor 的功能的支持。
通过包含用于收集跟踪、指标、日志和异常的 OpenTelemetry 检测库来实现自动遥测。
允许收集自定义遥测数据。
还支持使用实时指标监视和收集来自实时生产环境中 Web 应用程序的更多遥测数据。

要详细了解 Azure Monitor OpenTelemetry 发行版的优点，请参阅“我为什么应该使用 Azure Monitor OpenTelemetry 发行版”。

若要了解有关使用 OpenTelemetry 收集数据的详细信息，请参阅数据收集基础知识或 OpenTelemetry 常见问题解答。

OpenTelemetry 发布状态

OpenTelemetry 产品/服务适用于 .NET、Node.js、Python 和 Java 应用程序。有关每项功能的发布状态，请参阅常见问题解答。

使用 Application Insights 启用 OpenTelemetry

遵循本部分提供的步骤使用 OpenTelemetry 检测应用程序。针对特定于语言的说明选择选项卡。

注意

.NET 涉及多个场景，包括经典 ASP.NET、控制台应用、Windows 窗体 (WinForms) 等。

先决条件

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

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

提示

如果要从 Application Insights Classic API 迁移，请参阅我们的迁移文档。

安装客户端库

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

dotnet add package 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

修改你的应用程序

在 program.cs 类中，导入 Azure.Monitor.OpenTelemetry.AspNetCore 命名空间，添加 OpenTelemetry，并将其配置为使用 Azure Monitor：

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

var builder = WebApplication.CreateBuilder(args);

// Add OpenTelemetry and configure it to use Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

var app = builder.Build();

app.Run();

在 program.cs 类中，为每个 OpenTelemetry 信号添加 Azure Monitor 导出程序：

// 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.
// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/trace#tracerprovider-management
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.
// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/metrics#meterprovider-management
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter();

// Create a new logger factory.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/logs#logger-management
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(logging =>
    {
        logging.AddAzureMonitorLogExporter();
    });
});

注意

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

自动检测是通过配置更改启用的。不需更改代码。

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

注意

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

提示

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

提示

如果你要开发 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 
# APPLICATIONINSIGHTS_CONNECTION_STRING environment variable.
configure_azure_monitor()

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

连接字符串是唯一的，它可以指定 Azure Monitor OpenTelemetry 发行版将收集的遥测数据发送到的位置。

提示

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

要复制连接字符串：

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

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

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

重要

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

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

通过环境变量设置 - 推荐

将以下命令中的 <Your connection string> 替换为你的连接字符串。
```
APPLICATIONINSIGHTS_CONNECTION_STRING=<Your connection string>
```
通过配置文件设置 - 仅限 Java

创建包含以下内容的、名为 applicationinsights.json 的配置文件，并将其置于 applicationinsights-agent-.jar 所在的同一目录：
```
{
  "connectionString": "<Your connection string>"
}
```
将之前的 JSON 中的 <Your connection string> 替换为你的唯一连接字符串。
通过代码设置 - 仅限 ASP.NET Core、Node.js 和 Python

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

注意

如果在多个位置设置连接字符串，则环境变量的优先顺序如下：

代码
环境变量
配置文件

确认有数据流

运行应用程序，然后在 Azure 门户中打开 Application Insights。数据可能在数分钟后才会显示。

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

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

重要

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

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

示例应用程序

Azure Monitor OpenTelemetry 示例应用程序适用于所有支持的语言：

后续步骤

有关添加和修改 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 或浏览器用户监视。
若要查看常见问题解答、故障排除步骤、支持选项或提供 OpenTelemetry 反馈，请参阅有关 Azure Monitor Application Insights 的 OpenTelemetry 帮助、支持和反馈。

有关添加和修改 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 或浏览器用户监视。
若要查看常见问题解答、故障排除步骤、支持选项或提供 OpenTelemetry 反馈，请参阅有关 Azure Monitor Application Insights 的 OpenTelemetry 帮助、支持和反馈。

通过