OpenTelemetry 是由云原生计算基金会孵化的开源可观测性项目，它整合了 OpenTracing 和 OpenCensus 两个早期项目的能力，提供了一套统一的 API、SDK 和工具，用于收集应用的 traces（追踪）、metrics（指标）、logs（日志）三类核心遥测数据，并且支持将数据导出到 Jaeger、Zipkin、Prometheus 等多种后端存储和分析系统，大幅降低了分布式系统的可观测性接入成本。
OpenTelemetry 核心组件
在集成之前需要先了解几个核心概念，方便后续理解配置逻辑：
- TracerProvider：追踪提供器，负责管理追踪的采集、处理和导出逻辑，是 .NET 中接入追踪能力的核心入口。
- MeterProvider：指标提供器，负责指标的采集、聚合和导出，对应 metrics 数据的管理。
- Exporter：导出器，负责将采集到的遥测数据发送到指定的后端系统，不同后端对应不同的 Exporter 实现。
- Instrumentation：自动插桩库，针对 ASP.NET Core、HttpClient、EntityFrameworkCore 等常见组件提供自动遥测数据采集能力，减少手动埋点工作量。
.NET 应用集成 OpenTelemetry 步骤
1. 安装必要依赖包
以 ASP.NET Core 应用为例，首先需要安装对应的 NuGet 包，根据需求选择对应的组件：
- 基础追踪能力：
OpenTelemetry、OpenTelemetry.Extensions.Hosting - ASP.NET Core 自动插桩：
OpenTelemetry.Instrumentation.AspNetCore - HttpClient 自动插桩：
OpenTelemetry.Instrumentation.Http - 导出到 Jaeger 后端：
OpenTelemetry.Exporter.Jaeger
可以通过 NuGet 包管理器或者命令行安装：
dotnet add package OpenTelemetry dotnet add package OpenTelemetry.Extensions.Hosting dotnet add package OpenTelemetry.Instrumentation.AspNetCore dotnet add package OpenTelemetry.Instrumentation.Http dotnet add package OpenTelemetry.Exporter.Jaeger
2. 配置 TracerProvider
在 Program.cs 中添加 OpenTelemetry 追踪服务的配置，示例配置导出到本地运行的 Jaeger 服务：
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
var builder = WebApplication.CreateBuilder(args);
// 添加 OpenTelemetry 追踪服务
builder.Services.AddOpenTelemetry()
.WithTracing(tracerProviderBuilder =>
{
tracerProviderBuilder
// 设置资源信息，标识当前服务的名称
.SetResourceBuilder(ResourceBuilder.CreateDefault()
.AddService(serviceName: "DotNet-Demo-Service", serviceVersion: "1.0.0"))
// 添加 ASP.NET Core 自动插桩，采集 HTTP 请求相关追踪数据
.AddAspNetCoreInstrumentation(options =>
{
// 记录请求的真实状态码
options.EnrichWithHttpRequest = (activity, httpRequest) =>
{
activity.SetTag("http.request.path", httpRequest.Path);
};
})
// 添加 HttpClient 自动插桩，采集发出的 HTTP 请求追踪数据
.AddHttpClientInstrumentation()
// 添加控制台导出器，方便本地调试查看追踪数据
.AddConsoleExporter()
// 添加 Jaeger 导出器，导出数据到 Jaeger 后端
.AddJaegerExporter(options =>
{
options.AgentHost = "127.0.0.1";
options.AgentPort = 6831;
});
});
// 添加控制器服务
builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();
app.Run();
3. 自定义追踪数据埋点
除了自动插桩采集的数据，我们还可以在业务代码中手动添加自定义追踪 span，记录关键业务逻辑的执行情况：
using Microsoft.AspNetCore.Mvc;
using OpenTelemetry.Trace;
[ApiController]
[Route("api/[controller]")]
public class OrderController : ControllerBase
{
private static readonly ActivitySource OrderActivitySource = new ActivitySource("OrderService");
[HttpGet("create")]
public IActionResult CreateOrder()
{
// 创建自定义 span，记录订单创建逻辑
using (var activity = OrderActivitySource.StartActivity("CreateOrder"))
{
// 添加自定义标签，记录订单相关信息
activity?.SetTag("order.type", "normal");
activity?.SetTag("order.amount", 199.99);
// 模拟业务逻辑执行
Thread.Sleep(100);
// 记录事件，标记关键节点
activity?.AddEvent(new ActivityEvent("OrderCreated"));
return Ok("订单创建成功");
}
}
}
4. 集成指标（Metrics）能力
如果需要采集应用的指标数据，比如接口请求次数、接口耗时等，可以额外配置 MeterProvider：
using OpenTelemetry.Metrics;
// 在 Program.cs 的 AddOpenTelemetry 后追加指标配置
builder.Services.AddOpenTelemetry()
.WithTracing(/* 之前的追踪配置 */)
.WithMetrics(meterProviderBuilder =>
{
meterProviderBuilder
// 设置指标采集的服务信息
.SetResourceBuilder(ResourceBuilder.CreateDefault()
.AddService("DotNet-Demo-Service"))
// 添加 ASP.NET Core 指标自动采集，比如请求耗时、请求数量
.AddAspNetCoreInstrumentation()
// 添加进程指标采集，比如 CPU、内存使用
.AddProcessInstrumentation()
// 添加运行时指标采集，比如 GC 相关信息
.AddRuntimeInstrumentation()
// 添加 Prometheus 导出器，暴露指标接口供 Prometheus 采集
.AddPrometheusExporter();
});
// 如果需要暴露 Prometheus 指标接口，还需要添加对应中间件
app.MapPrometheusScrapingEndpoint();
验证集成效果
完成配置后启动应用，访问对应的接口，就可以在 Jaeger 的 UI 界面（默认地址为 http://127.0.0.1:16686）中看到对应的追踪链路，在 Prometheus 中可以看到对应的指标数据。如果配置了控制台导出器，也可以在应用的控制台输出中看到格式化的遥测数据，方便快速验证集成是否生效。
注意事项
- 生产环境建议关闭控制台导出器，避免过多的日志输出影响应用性能。
- 可以根据实际需求选择对应的 Exporter，不需要同时配置所有导出器。
- 自动插桩库会根据组件版本提供对应的支持，安装时注意版本兼容性，避免版本冲突。
- 如果需要采集日志数据，可以结合
OpenTelemetry.Logs相关的包进行配置，流程和追踪、指标类似。
OpenTelemetry.NET分布式追踪遥测数据修改时间：2026-07-22 06:54:29