# 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 配置键
```json
"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/开关后重启即可。