跳到主要内容
版本：3.0.0

OpenTelemetry 链路追踪（Aegis.Trace.OpenTelemetry）

Aegis.Trace.OpenTelemetry 负责把当前服务接入 OpenTelemetry tracing，并将链路输出到 OTLP 端点或控制台。它当前聚焦的是追踪链路，而不是 Prometheus 指标暴露。

组件概览​

字段说明
组件名称OpenTelemetry 链路追踪
真实类库Aegis.Trace.OpenTelemetry
组件定位服务链路采集与 OTLP 导出组件
引入方式安装 NuGet，并在 Component.deps.json 的 Services 中启用 OpenTelemetry
组件声明OpenTelemetry
核心能力ASP.NET Core 请求追踪、HttpClient 追踪、异常记录、OTLP / 控制台导出
主要配置OpenTelemetry:Enabled、OpenTelemetry:ServiceName、OpenTelemetry:App、OpenTelemetry:Endpoint
典型配套Prometheus 指标监控

什么时候要用它​

适合场景：

  • 你要看一次请求跨服务的调用链
  • 你要把 tracing 数据发到 OTLP 收集端
  • 你要在排查慢接口、异常请求或外部调用问题时保留追踪信息

最小可运行路径​

第一步：安装组件​

dotnet add package Aegis.Trace.OpenTelemetry

第二步：在 Component.deps.json 中启用 OpenTelemetry​

当前生效点在服务注册阶段，标准接法先放到 Services 即可。

{
  "Components": {
    "Services": [
      "OpenTelemetry"
    ],
    "Middlewares": []
  }
}

第三步：准备配置​

{
  "OpenTelemetry": {
    "Enabled": true,
    "ServiceName": "His::Settlement",
    "App": "Api",
    "Endpoint": "http://localhost:4317"
  }
}

配置项怎么理解​

配置项作用
Enabled是否启用追踪组件
ServiceName服务主名称
App当前应用名，最终会拼进服务名
EndpointOTLP 输出地址；为空时输出到控制台

需要注意一件事：当前服务名会按 ServiceName::App 拼接，所以如果配置了：

{
  "OpenTelemetry": {
    "ServiceName": "His::Settlement",
    "App": "Api"
  }
}

最终追踪里看到的服务名会是：

His::Settlement::Api

组件默认采集什么​

当前默认会接入：

  • ASP.NET Core 请求追踪
  • HttpClient 外部调用追踪
  • 异常信息记录

并且会过滤以下路径，避免把观测端点本身也采进链路：

  • /metrics
  • /health
  • /swagger

导出方式怎么判断​

配置状态实际行为
Endpoint 已配置导出到 OTLP 端点
Endpoint 为空输出到控制台

如果你只是本地联调，可以先让它输出到控制台；接到正式观测平台时，再改成 OTLP 地址。

接入后怎么确认生效​

通常用下面几项验收：

  • 应用启动后没有 OpenTelemetry 初始化报错
  • 请求一个普通接口时，控制台或 OTLP 后端能看到链路
  • 请求里包含外部 HttpClient 调用时，链路里能看到下游 Span
  • /swagger、/metrics 不会出现在追踪链路里

和 Prometheus 的区别​

  • OpenTelemetry：看链路、Span、异常、跨服务调用过程
  • Prometheus：看指标、计数、时延、并发量

因此更推荐的组合是：

  • 先用 Prometheus 建基础监控
  • 再用 OpenTelemetry 做链路排障

常见问题​

启用了组件，但什么都没看到​

优先检查：

  • OpenTelemetry:Enabled 是否为 true
  • Endpoint 是否指向可用的 OTLP 地址
  • 如果 Endpoint 留空，是否有看控制台输出

服务名看起来比预期多一段​

这是当前组件的正常行为，因为它会把 ServiceName 和 App 拼成一个最终服务名。