跳到主要内容
版本：3.0.0

OpenTelemetry

这页对应 3.x 里的链路追踪接入方式，核心组件是 OpenTelemetry 链路追踪（Aegis.Trace.OpenTelemetry）。

先看 OpenTelemetry 在框架里的职责​

当前这层能力主要负责：

  • 采集 ASP.NET Core 请求链路
  • 采集 HttpClient 外部调用链路
  • 记录异常信息
  • 输出到 OTLP 端点或控制台

它当前不负责 Prometheus 指标暴露，所以指标监控仍然看 Prometheus。

最小接入方式​

1. 启用组件​

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

2. 准备配置​

{
  "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 指向对应地址。

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

接入后怎么验收​

建议至少做这几项：

  1. 启动时确认没有 OpenTelemetry 初始化报错
  2. 请求一个普通接口，确认控制台或后端能看到链路
  3. 触发一次外部 HttpClient 调用，确认链路里能看到下游 Span
  4. 打开 /swagger、/metrics，确认这些路径不会被采进链路

常见问题​

什么都没输出​

优先检查：

  • Enabled 是否为 true
  • Endpoint 是否可达
  • 若 Endpoint 留空，是否有关注控制台输出

为什么服务名会多出一段 ::Api​

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