为 .NET、Java、Node.js和 Python 应用程序添加和修改 OpenTelemetry

注意

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

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

本指南提供关于集成和自定义 OpenTelemetry（OTel）工具至 Azure Monitor Application Insights 的说明。

将 Microsoft OpenTelemetry 发行版用于 .NET、Node.js和 Python。 Java继续使用 Azure Monitor 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

在启动未在代码中设置它的示例之前，先设置 APPLICATIONINSIGHTS_CONNECTION_STRING。 使提供程序在应用程序生存期内保持活动状态，并在关闭时刷新遥测数据。 在加载应用程序库之前初始化 Node.js 插桩；ESM 应用程序必须预加载 Microsoft OpenTelemetry 发行版加载程序。

若要了解有关 OpenTelemetry 概念的详细信息，请参阅 OpenTelemetry 概述。

注意

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

添加社区工具库

有关每个分发版随附的库，请参阅 自动数据收集和资源检测器。

当您使用 OpenTelemetry 社区的工具库时，可以自动收集更多数据。

注意

我们不支持也不保证社区检测库的质量。 要为我们的发行版推荐一个，请在反馈社区中发帖或投票。 请注意，某些检测基于实验性的 OpenTelemetry 规范，未来可能会引入中断性变更。

若要添加社区库，请在为库添加 NuGet 包后使用 ConfigureOpenTelemetryMeterProvider 或 ConfigureOpenTelemetryTracerProvider 方法。

以下示例演示如何添加 运行时检测 以收集额外的指标：

dotnet add package OpenTelemetry.Instrumentation.Runtime

// Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;
using OpenTelemetry.Metrics;

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add runtime instrumentation.
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) =>
    builder.AddRuntimeInstrumentation());

// Configure the Microsoft OpenTelemetry Distro.
// Export collected telemetry to Azure Monitor.
builder.Services.AddOpenTelemetry().UseMicrosoftOpenTelemetry(options =>
    options.Exporters = ExportTarget.AzureMonitor);

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

收集自定义遥测数据

本部分介绍如何从应用程序收集自定义遥测数据。

根据语言和信号类型，可以通过不同的方式收集自定义遥测数据，包括：

  • 开放遥测 API
  • 特定于语言的日志记录/指标库

注意

不支持针对 Java 的 Micrometer Tracing API。

下表显示了目前支持的自定义遥测类型：

语言 自定义事件 自定义指标 依赖项 异常 页面视图 请求 痕迹
ASP.NET Core
   开放遥测 API 是 是 是 是
    ILogger 应用程序接口 是 是
Java
   开放遥测 API 是 是 是 是 是
   Logback，Log4j，JUL 是 是
   Micrometer 指标 是
Node.js
   开放遥测 API 是 是 是 是 是
Python
   开放遥测 API 是 是 是 是
   Python日志记录模块 是
   事件扩展模块 是 是

添加自定义指标

在此上下文中，自定义指标术语是指手动检测代码以收集超出 OpenTelemetry Instrumentation 库自动收集的额外指标。 要详细了解如何使用指标，请参阅 Application Insights 中的指标。

OpenTelemetry API 提供六种度量工具，以涵盖各种度量方案。当在指标资源管理器中可视化指标时，需要选取正确的聚合类型。 使用 OpenTelemetry 指标 API 发送指标和使用检测库时，此要求是正确的。

下表显示了每个 OpenTelemetry 度量工具的建议聚合类型。

OpenTelemetry 工具 Azure Monitor聚合类型
计数器 总和
异步计数器 总和
直方图 最小值、最大值、平均值、总和和计数
异步仪表 平均值
UpDownCounter 总和
异步增减计数器 总和

注意

在大多数情况下，其他聚合类型没有意义。

OpenTelemetry 规范介绍了这些工具，并提供了每种工具使用的示例。

提示

直方图是用于记录分布的最通用的 OpenTelemetry 指标工具。 Azure Monitor目前将直方图工具展平为五种聚合类型，并且对百分位数的支持正在开发中。 虽然通用性较低，但其他 OpenTelemetry 仪器对应用程序性能的影响较小。

直方图示例

应用程序启动时必须按名称订阅仪表：

// Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;
using OpenTelemetry.Metrics;

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named
// "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter(
    "OTel.AzureMonitor.Demo"));

// Configure the Microsoft OpenTelemetry Distro.
// Export collected telemetry to Azure Monitor.
builder.Services.AddOpenTelemetry().UseMicrosoftOpenTelemetry(options =>
    options.Exporters = ExportTarget.AzureMonitor);

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Meter 必须使用同一名称初始化：

using System.Diagnostics.Metrics;

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new histogram metric named "FruitSalePrice".
Histogram<long> myFruitSalePrice = meter.CreateHistogram<long>("FruitSalePrice");

// Create a new Random object.
var rand = new Random();

// Record a few random sale prices for apples and lemons, with different colors.
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "green"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));

反例

应用程序启动时必须按名称订阅仪表：

// Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;
using OpenTelemetry.Metrics;

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named
// "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter(
    "OTel.AzureMonitor.Demo"));

// Configure the Microsoft OpenTelemetry Distro.
// Export collected telemetry to Azure Monitor.
builder.Services.AddOpenTelemetry().UseMicrosoftOpenTelemetry(options =>
    options.Exporters = ExportTarget.AzureMonitor);

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Meter 必须使用同一名称初始化：

using System.Diagnostics.Metrics;

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new counter metric named "MyFruitCounter".
Counter<long> myFruitCounter = meter.CreateCounter<long>("MyFruitCounter");

// Record the number of fruits sold, grouped by name and color.
myFruitCounter.Add(1, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(2, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(1, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(2, new("name", "apple"), new("color", "green"));
myFruitCounter.Add(5, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(4, new("name", "lemon"), new("color", "yellow"));

量表示例

应用程序启动时必须按名称订阅仪表：

// Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;
using OpenTelemetry.Metrics;

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named
// "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter(
    "OTel.AzureMonitor.Demo"));

// Configure the Microsoft OpenTelemetry Distro.
// Export collected telemetry to Azure Monitor.
builder.Services.AddOpenTelemetry().UseMicrosoftOpenTelemetry(options =>
    options.Exporters = ExportTarget.AzureMonitor);

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Meter 必须使用同一名称初始化：

using System.Diagnostics;
using System.Diagnostics.Metrics;

// Get the current process.
var process = Process.GetCurrentProcess();

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new observable gauge metric named "Thread.State".
// This metric will track the state of each thread in the current process.
ObservableGauge<int> myObservableGauge = meter.CreateObservableGauge("Thread.State", (
    ) => GetThreadState(process));

static IEnumerable<Measurement<int>> GetThreadState(Process process)
{
    // Iterate over all threads in the current process.
    foreach (ProcessThread thread in process.Threads)
    {
        // Create a measurement for each thread, including the thread state, process ID,
        // and thread ID.
        yield return new((int)thread.ThreadState, new("ProcessId", process.Id), new(
            "ThreadId", thread.Id));
    }
}

添加自定义异常

选择的检测库会自动将异常情况报告给 Application Insights。 不过，你可能希望手动报告一些仪器库未报告的例外情况。 例如，通常不会报告代码捕获的异常。 你可能希望报告这些问题，以便在相关体验中引起注意，尤其是在故障部分和端到端事务视图中。

.NET 示例是已插桩的应用程序的片段。 对于活动示例，请使用在activitySource中注册的。 对于日志记录示例，请使用应用程序配置的 ILoggerFactory 作为 loggerFactory。

  • 要使用活动记录异常事件：

    using System.Diagnostics;
using OpenTelemetry.Trace;

// Start a new activity named "ExceptionExample".
using (var activity = activitySource.StartActivity("ExceptionExample"))
{
    // Try to execute some code.
    try
    {
        throw new Exception("Test exception");
    }
    // If an exception is thrown, catch it and set the activity status to "Error".
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error);
        activity?.RecordException(ex);
    }
}

  • 要使用 ILogger 记录异常：

    // Create a logger using the logger factory. The logger category name is used to filter
// and route log messages.
var logger = loggerFactory.CreateLogger("ExceptionExample");

// Try to execute some code.
try
{
    throw new Exception("Test Exception");
}
catch (Exception ex)
{
    // Log an error message with the exception. The log level is set to "Error" and the
    // event ID is set to 0.
    // The log message includes a template and a parameter. The template will be replaced
    // with the value of the parameter when the log message is written.
    logger.Log(
        logLevel: LogLevel.Error,
        eventId: 0,
        exception: ex,
        message: "Hello {name}.",
        args: new object[] { "World" });
}

添加自定义范围

你可能想要在两种情况下添加自定义跨度。 首先，当存在仪器库尚未收集的依赖请求时。 其次，当你希望在端到端事务视图上将应用程序进程建模为跨度时。

注意

Activity 命名空间中的 ActivitySource 和 System.Diagnostics 类分别代表 Span 和 Tracer 的 OpenTelemetry 概念。 可以通过使用其构造函数而不是使用 ActivitySource 来直接创建 TracerProvider。 每个 ActivitySource 类都必须显式地通过 TracerProvider 来连接到 AddSource()。 这是因为 OpenTelemetry 跟踪 API 的某些部分直接合并到.NET运行时中。 若要了解详细信息，请参阅 OpenTelemetry .NET 跟踪 API 的简介。

添加自定义跨度 
// Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;
using System.Diagnostics;
using OpenTelemetry.Trace;

// Define an activity source named "ActivitySourceName". This activity source will be used
// to create activities for all requests to the application.
using var activitySource = new ActivitySource("ActivitySourceName");

// Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a source named "ActivitySourceName".
// This will ensure that all activities created by the activity source are traced.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) =>
    builder.AddSource("ActivitySourceName"));

// Configure the Microsoft OpenTelemetry Distro. This service will collect
// and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseMicrosoftOpenTelemetry(options =>
    options.Exporters = ExportTarget.AzureMonitor);

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

// Map a GET request to the root path ("/") to the specified action.
app.MapGet("/", () =>
{
    // Start a new activity named "CustomActivity". This activity will be traced and the
    // trace data will be sent to Azure Monitor.
    using (var activity = activitySource.StartActivity("CustomActivity"))
    {
        // your code here
    }

    // Return a response message.
    return $"Hello World!";
});

// Start the ASP.NET Core application.
app.Run();

StartActivity 默认为 ActivityKind.Internal，但你可以提供任何其他 ActivityKind。 ActivityKind.Client、ActivityKind.Producer、ActivityKind.Internal 映射到 Application Insights dependencies。 ActivityKind.Server、ActivityKind.Consumer 映射到 Application Insights requests。

发送自定义事件

Application Insights 将自定义事件 customEvents 存储在表中。 分析、筛选和可视化它们的一种方法是使用 Application Insights 使用情况体验。

如果要自动收集客户端交互事件，可以在 JavaScript SDK 中使用插件。

用于 .NET 的 Microsoft OpenTelemetry Distro 通过 Azure Monitor 日志记录导出程序发送自定义事件。

若要使用 CustomEvent 发送 ILogger，请设置消息模板中的 "microsoft.custom_event.name" 属性。

// Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;

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

// Configure the Microsoft OpenTelemetry Distro.
builder.UseMicrosoftOpenTelemetry(options =>
{
    options.Exporters = ExportTarget.AzureMonitor;
});

// Build the application with the configured telemetry services.
var app = builder.Build();

// Use the message-template attribute to name the custom event.
app.Logger.LogInformation("{microsoft.custom_event.name} {additional_attrs}",
    "test-event-name", "val1");

// Run the application and its telemetry providers.
app.Run();

修改遥测

本部分介绍如何修改遥测。

添加范围属性

这些属性可能包括向遥测添加自定义属性。 还可以使用属性来设置 Application Insights 架构中的可选字段，如客户端 IP。

将自定义属性添加到 Span

你添加到范围的任何属性都将导出为自定义属性。 它们将填充请求、依赖项、跟踪或异常表中的 customDimensions 字段。

若要添加范围属性，请使用以下两种方法之一：

  • 使用检测库提供的选项。
  • 添加自定义范围处理器。

提示

使用检测库提供的选项（当它们可用时）的优点是整个上下文都可用。 因此，用户可以选择添加或筛选更多属性。 例如，HttpClient 检测库中的扩充选项让用户可以访问 HttpRequestMessage 和 HttpResponseMessage 本身。 他们可以从中选择任何内容并将其存储为属性。

  1. 许多检测库都提供扩充选项。 有关指南，请参阅各个检测库的自述文件：

  2. 使用自定义处理器：

    提示

    添加此处显示的处理器之前添加Azure Monitor。

    // Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;
using OpenTelemetry.Trace;

// Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a new processor named
// ActivityEnrichingProcessor.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) =>
    builder.AddProcessor(new ActivityEnrichingProcessor()));

// Configure the Microsoft OpenTelemetry Distro. This service will collect
// and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseMicrosoftOpenTelemetry(options =>
    options.Exporters = ExportTarget.AzureMonitor);

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

// Start the ASP.NET Core application.
app.Run();

    使用以下代码将 ActivityEnrichingProcessor.cs 添加到你的项目：

    using System.Diagnostics;
using OpenTelemetry;

public class ActivityEnrichingProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        // The updated activity will be available to all processors which are called after
        // this processor.
        activity.DisplayName = "Updated-" + activity.DisplayName;
        activity.SetTag("CustomDimension1", "Value1");
        activity.SetTag("CustomDimension2", "Value2");
    }
}

设置用户 IP

可以通过在 span 上设置属性来填充请求的 client_IP 字段。 Application Insights 使用 IP 地址生成用户位置属性，然后默认放弃它。

使用自定义属性示例，但替换 ActivityEnrichingProcessor.cs 中的以下代码行：

// Add the client IP address to the activity as a tag.
// only applicable in case of activity.Kind == Server
activity.SetTag("client.address", "<IpAddress>");

设置用户 ID 或经过身份验证的用户 ID

可以使用以下指南为请求填充 user_Id 或 user_AuthenticatedId 字段。 用户 ID 是匿名用户标识符。 经过身份验证的用户 ID 是已知的用户标识符。

重要

在设置经过身份验证的用户 ID 之前，请参考适用的隐私法律。

使用自定义属性示例：

// Add the user ID to the activity as a tag, but only if the activity is not null.
activity?.SetTag("enduser.id", "<UserId>");

添加日志属性

OpenTelemetry 使用 .NET 的 ILogger。 可以使用消息模板将自定义维度附加到日志。

覆盖 HTTP 4xx 响应中的请求错误状态

可以阻止 Application Insights 将 4xx 响应计数为错误。

以下代码显示了将 HTTP 4xx 响应标记为成功的自定义活动处理器。

处理器：

using System.Diagnostics;
using OpenTelemetry;

public class Http4xxSuccessProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        if (activity.Kind == ActivityKind.Server)
        {
            var statusCodeTag = activity.GetTagItem("http.response.status_code");
            if (statusCodeTag is int statusCode && statusCode >= 400 && statusCode < 500)
            {
                // Set status to Ok to bypass the Azure Monitor exporter's default logic
                // which treats any HTTP 4xx as failure when status is Unset.
                // The response code tag (e.g., 400) remains unchanged — only the
                // success field in Application Insights is affected.
                activity.SetStatus(ActivityStatusCode.Ok);
            }
        }

        base.OnEnd(activity);
    }
}

注册：

// Import the Microsoft OpenTelemetry Distro and supporting APIs.
using Microsoft.OpenTelemetry;
using OpenTelemetry.Trace;

// Create the application builder.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing.AddProcessor<Http4xxSuccessProcessor>())

    // Configure the Microsoft OpenTelemetry Distro.
    .UseMicrosoftOpenTelemetry(options =>
    {
        options.Exporters = ExportTarget.AzureMonitor;

        // Set the connection string for Azure Monitor export.
        options.AzureMonitor.ConnectionString = "<ConnectionString>";
    });

// Build the application with the configured telemetry services.
var app = builder.Build();

// Run the application and its telemetry providers.
app.Run();

获取追踪 ID 或跨度 ID

要获取当前处于活动状态的跨度中的Trace ID和Span ID，请使用以下步骤。

注意

Activity 命名空间中的 ActivitySource 和 System.Diagnostics 类分别代表 Span 和 Tracer 的 OpenTelemetry 概念。 这是因为 OpenTelemetry 跟踪 API 的某些部分直接合并到.NET运行时中。 若要了解详细信息，请参阅 OpenTelemetry .NET 跟踪 API 的简介。

using System.Diagnostics;

// Get the current activity.
Activity activity = Activity.Current;
// Get the trace ID of the activity.
string traceId = activity?.TraceId.ToHexString();
// Get the span ID of the activity.
string spanId = activity?.SpanId.ToHexString();

故障排除、反馈和支持

提示

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

故障排除

OpenTelemetry 反馈

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

支持

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

后续步骤

  • 上次更新时间为