TakeoutSaaS.AdminApi/Document/14_OpenTelemetry接入指引.md

14_OpenTelemetry 接入指引

现状：Admin/Mini/User API 已集成 OTel 埋点，可导出到 Collector/控制台/文件日志，默认关闭 OTLP 导出。

1. 依赖与版本

• NuGet：OpenTelemetry.Extensions.Hosting、OpenTelemetry.Instrumentation.AspNetCore、OpenTelemetry.Instrumentation.Http、OpenTelemetry.Instrumentation.EntityFrameworkCore、OpenTelemetry.Instrumentation.Runtime、OpenTelemetry.Exporter.OpenTelemetryProtocol、OpenTelemetry.Exporter.Console。
• 当前 EF Core instrumentation 由 NuGet 回退到 1.10.0-beta.1（会提示 NU1603/NU1902），待可用时统一升级到稳定版以消除告警。

2. 程序内配置（Admin/Mini/User API）

• Resource：ServiceName 分别为 TakeoutSaaS.AdminApi|MiniApi|UserApi，ServiceInstanceId = Environment.MachineName。
• Tracing：开启 ASP.NET Core、HttpClient、EF Core（禁用 SQL 文本）、Runtime；采样器默认 ParentBased + AlwaysOn。
• Metrics：开启 ASP.NET Core、HttpClient、Runtime。
• Exporter：
  • OTLP（可选）：读取 Otel:Endpoint，非空时启用。
  • Console：Otel:UseConsoleExporter（默认 Dev 开启，Prod 关闭）。
• 日志：Serilog 输出 Console + 文件（按天滚动，保留 7 天），模板已包含 TraceId/SpanId（通过 Enrich FromLogContext）。

3. appsettings 配置键

"Otel": {
  "Endpoint": "",                 // 为空则不推 OTLP，例如 http://otel-collector:4317
  "Sampling": "ParentBasedAlwaysOn",
  "UseConsoleExporter": true      // Dev 默认 true，Prod 建议 false
}

• 环境变量可覆盖：OTEL_SERVICE_NAME、OTEL_EXPORTER_OTLP_ENDPOINT 等。

4. Collector/后端接入建议

• Collector 监听 4317/4318（gRPC/HTTP OTLP），做采样/脱敏/分流，再转发 Jaeger/Tempo/ELK/Datadog 等。
• 生产注意：限制导出 SQL 文本（已关闭）、对敏感字段脱敏，必要时在 Collector 做 TraceIdRatioBased 采样以控量。

5. 验证步骤

1. 开启 Otel:UseConsoleExporter=true，本地运行 API，观察控制台是否输出 Span/Metric。
2. 配置 Otel:Endpoint=http://localhost:4317 并启动 Collector，使用 Jaeger/Tempo UI 或 curl http://localhost:4318/v1/traces 验证链路。
3. 文件日志：查看 logs/admin-api-*.log 等，确认包含 TraceId/SpanId。

6. 后续工作

• 待 NuGet 源更新后，升级到稳定版 OTel 包并消除 NU1603/NU1902 告警。
• 如需采集日志到 ELK，可直接用 Filebeat/Vector 读取 logs/*.log 推送，无需改代码。
• 如需控制采样率或关闭某些 instrumentation，调整 appsettings 中的 Sampling/开关后重启即可。