120 lines
8.9 KiB
Markdown
120 lines
8.9 KiB
Markdown
---
|
||
name: OpenTelemetry三信号完整接入
|
||
overview: 实现 OpenTelemetry Traces/Metrics/Logs 三大信号的完整初始化与 OTLP gRPC 导出，补齐当前 main.go 引用的未实现桩（NewOTelProvider/OTelShutdown），保持本地日志不变的同时新增 OTel 导出，并加优雅关闭以刷新数据。
|
||
todos:
|
||
- id: deps-and-globals
|
||
content: 补齐 otel sdk/exporter/otelslog/runtime 依赖（go mod tidy），在 global/otel.go 新增 OTelShutdown 与 Meter 变量，并对齐 config.yaml 与 config.example.yaml 的 SamplerRatio 键名
|
||
status: completed
|
||
- id: provider
|
||
content: 实现 pkg/tracing/provider.go 的 NewOTelProvider：构建 Resource 与 Tracer/Meter/Logger 三 Provider、OTLP gRPC 导出、runtime 指标、采样与 Enabled/Insecure 开关、no-op 降级、聚合 Shutdown
|
||
status: completed
|
||
dependencies:
|
||
- deps-and-globals
|
||
- id: log-fanout
|
||
content: 实现 pkg/tracing/fanout.go 扇出 slog.Handler，将日志同时输出到本地 JSON（保留 OtelContextHandler）与 otelslog bridge
|
||
status: completed
|
||
dependencies:
|
||
- provider
|
||
- id: wire-main
|
||
content: 修改 main.go：修正 setupOTel 符号与错误降级、调整 init 顺序使 logger 桥接 LoggerProvider、setupSlogLogger 接入扇出 handler、main() 增加 SIGINT/SIGTERM 监听与 server.Shutdown + OTelShutdown 优雅关闭
|
||
status: completed
|
||
dependencies:
|
||
- provider
|
||
- log-fanout
|
||
- id: verify
|
||
content: 执行 go mod tidy 与 go build/go vet 全量验证，smoke 验证 Enabled=false 及采集器不可用时不 panic 并正常启动，清理临时验证文件
|
||
status: completed
|
||
dependencies:
|
||
- wire-main
|
||
---
|
||
|
||
## 产品概述
|
||
|
||
为「衣柜/穿搭」后端补齐 OpenTelemetry 三大信号（Traces / Metrics / Logs）的完整初始化与 OTLP gRPC 导出，把当前"只埋点、未导出"的半接入状态升级为可真正观测的完整链路，并修复因待实现桩导致的编译失败问题。
|
||
|
||
## 核心功能
|
||
|
||
- **Traces（链路追踪）**：注册真实 TracerProvider（Resource + OTLP gRPC 批量导出 + 采样率），使全项目已有的 span 与 gin 请求 span 真正导出。
|
||
- **Metrics（指标）**：注册 MeterProvider（OTLP gRPC 周期导出），采集 Go runtime 指标，并预留自定义指标入口。
|
||
- **Logs（日志）**：新增 OTel 日志导出（otelslog 桥接），同时保留现有本地 JSON 日志（文件+stdout，含 trace_id/span_id 注入）。
|
||
- **优雅关闭**：进程收到退出信号时先关闭 HTTP 服务，再刷新并关闭三个 Provider，避免丢失缓冲数据。
|
||
- **开关与降级**：尊重配置 `Enabled` 开关；未启用或采集器不可用时降级为 no-op，服务照常启动、业务不受影响、不 panic。
|
||
|
||
## 技术栈
|
||
|
||
- 语言/框架：Go 1.27 + Gin（沿用现有项目），OpenTelemetry-Go SDK。
|
||
- 基准版本对齐现有 `go.opentelemetry.io/otel v1.46.0`；SDK trace/metric 用对应 v1.46.x，log 相关为配套 v0.x，由 `go mod tidy` 解析。
|
||
- 传输：OTLP over gRPC，导出到配置的 `ExporterEndpoint`（如 `127.0.0.1:4317`）。
|
||
|
||
## 实现思路
|
||
|
||
在 `pkg/tracing` 新增统一初始化入口 `NewOTelProvider`，一次性构建 Resource 与三个 SDK Provider（Tracer/Meter/Logger），设置到 otel 全局，并返回聚合的 shutdown 函数；`main.go` 修正现有待实现桩（`setupOTel` 引用的未定义符号）、修正 init 顺序与错误降级、补充信号监听与优雅关闭。业务层 100+ 处 `global.Tracer.Start(...)` 与 `otelgin.Middleware(...)` 无需改动，Provider 注册后立即生效。
|
||
|
||
### 关键技术决策
|
||
|
||
- **统一入口 + 聚合 Shutdown**：单一 `NewOTelProvider` 返回 `(trace.Tracer, func(ctx) error, error)`，内部聚合三个 Provider 的 Shutdown，`main` 只持有一个 `global.OTelShutdown`，降低接线复杂度与遗漏 flush 风险。
|
||
- **日志扇出（fanout）而非替换**：保留现有本地 JSON handler（含 `OtelContextHandler` 的 trace 注入），叠加 `otelslog` bridge handler，用一个极简自研 `slog.Handler` 扇出到两者，避免引入第三方 slog-multi 依赖，且不破坏现有日志落盘。
|
||
- **降级优先，保障可用性**：`Enabled=false` 或 exporter 建立失败时，`global.Tracer` 使用 no-op tracer（业务层 `Tracer.Start` 安全非 nil），`OTelShutdown` 为空实现；`Insecure=true` 用非 TLS gRPC（内网采集器语义，不额外放开外网）。
|
||
- **批处理与性能**：Trace 用 BatchSpanProcessor、Metric 用 PeriodicReader、Log 用 BatchProcessor，均为异步批量导出，热路径开销可控；采样由 `SamplerRatio` 控制（`ParentBased(TraceIDRatioBased)`），对 <=0 做默认兜底 1.0。
|
||
|
||
## 实现要点（防回归）
|
||
|
||
- **编译阻断修复**：`main.go` 现引用未定义符号 `tracing.NewOTelProvider`、`global.OTelShutdown`、`global.OTelSetting`（真实名为 `global.OtelSetting`）。需实现前两者、并把 setupOTel 内改回 `global.OtelSetting`，使项目恢复可编译。
|
||
- **配置键名对齐 bug**：`config.example.yaml` 使用 `SampleRatio`，而 `setting.OtelSettingS` 字段为 `SamplerRatio`（拼写不一致 → viper 读不到 → 采样率 0 → 不采样）。统一为 `SamplerRatio`（改 yaml 键），并在代码对 ratio<=0 兜底 1.0。同时 `configs/config.yaml`（实际运行配置）若存在同样键名需一并对齐。
|
||
- **init 顺序**：需保证 setupOTel 在 setupSlogLogger 之前完成 LoggerProvider 构建，slog 扇出才能拿到 bridge；或 setupSlogLogger 在 provider 就绪后重建默认 logger。
|
||
- **错误处理**：setupOTel 失败时告警不 panic（保持服务可启动），并降级 no-op。
|
||
- **优雅关闭**：`main()` 当前直接 `ListenAndServe`，需改为监听 SIGINT/SIGTERM，先 `http.Server.Shutdown(ctx)` 再 `global.OTelShutdown(ctx)`，设置合理超时（如 5s）避免卡死。
|
||
- 复用现有 `internal/middleware/otel.go`（otelgin）与 `pkg/tracing/otel.go`（OtelContextHandler），不重复造轮子。
|
||
|
||
## 架构与数据流
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[HTTP 请求] --> B[otelgin 中间件 server span]
|
||
B --> C[handler/service/dao<br/>global.Tracer.Start 子 span]
|
||
C --> D[slog 扇出 Handler]
|
||
D --> E[本地 JSON 文件+stdout<br/>OtelContextHandler 注入 trace_id]
|
||
D --> F[otelslog bridge]
|
||
C --> G[TracerProvider<br/>BatchSpanProcessor]
|
||
C --> H[MeterProvider<br/>PeriodicReader + runtime 指标]
|
||
F --> I[LoggerProvider<br/>BatchProcessor]
|
||
G --> J[(OTLP gRPC Collector<br/>ExporterEndpoint)]
|
||
H --> J
|
||
I --> J
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
zt-closet-backend/
|
||
├── go.mod / go.sum # [MODIFY] go mod tidy 补 otel sdk / sdk-metric / sdk-log / resource+semconv /
|
||
│ # exporters/otlp/{otlptracegrpc, otlpmetricgrpc, otlploggrpc} /
|
||
│ # contrib/instrumentation/runtime / contrib/bridges/otelslog / log/global
|
||
├── global/
|
||
│ └── otel.go # [MODIFY] 保留 Tracer；新增 OTelShutdown func(context.Context) error、
|
||
│ # Meter metric.Meter（可选自定义指标入口）、LoggerProvider（可选）
|
||
├── pkg/
|
||
│ ├── setting/section.go # [MODIFY] 若选择改字段则同步；默认优先改 yaml 对齐字段（本方案改 yaml，section 不动）
|
||
│ └── tracing/
|
||
│ ├── otel.go # [KEEP] OtelContextHandler 保留
|
||
│ ├── provider.go # [NEW] NewOTelProvider：构建 Resource + Tracer/Meter/Logger Provider +
|
||
│ │ # OTLP gRPC 导出 + runtime 指标 + 采样 + Enabled/Insecure 开关 +
|
||
│ │ # no-op 降级 + 聚合 shutdown
|
||
│ └── fanout.go # [NEW] fanoutHandler：极简 slog.Handler，将日志同时发给本地 handler 与 otelslog bridge
|
||
├── internal/middleware/
|
||
│ └── otel.go # [KEEP] otelgin 中间件，无需改
|
||
├── configs/
|
||
│ ├── config.example.yaml # [MODIFY] OTel 段键名对齐 SamplerRatio，校正注释
|
||
│ └── config.yaml # [MODIFY] 若存在同名键，一并对齐 SamplerRatio（运行时实际读取）
|
||
└── main.go # [MODIFY] 修正 setupOTel 符号与错误降级；调整 init 顺序；
|
||
# setupSlogLogger 使用扇出 handler；main() 加信号监听 + 优雅关闭
|
||
```
|
||
|
||
## 关键代码结构（接口约定）
|
||
|
||
```
|
||
// pkg/tracing/provider.go —— 统一初始化入口
|
||
// 返回：全局 Tracer、聚合 Shutdown（flush 三个 Provider）、错误
|
||
// Enabled=false 或初始化失败时返回 no-op Tracer + 安全空 Shutdown
|
||
func NewOTelProvider(cfg *setting.OtelSettingS) (trace.Tracer, func(context.Context) error, error)
|
||
``` |