feat(observability): 接入 Prometheus 指标与 OpenTelemetry/Tempo 链路

[gac0812]

接入方案

Prometheus 指标

进程暴露 GET /metrics，供 Prometheus scrape。标签使用封闭枚举，避免基数爆炸。

覆盖面：

• HTTP：in-flight、QPS、p50/p95、鉴权 / snapshot / reminder 结果、health liveness、依赖就绪
• WebSocket：handshake / disconnect、在线连接与会话、音频 chunk / 截断 / 队列深度
• Voice / Agent：turn 结果、ASR→LLM→TTS 各阶段耗时、工具调用次数与耗时
• External：ASR / LLM / TTS / maps / realtime 的请求量、总耗时、TTFB、in-flight、LLM token 计数
• Database：SELECT/INSERT/UPDATE 等语句次数与 p95、连接池 size / checked out

OpenTelemetry → Tempo

配置 TIMEFLOW_OTEL_EXPORTER_OTLP_ENDPOINT 后导出 trace（TIMEFLOW_OTEL_SERVICE_NAME=timeflow-backend）。未配置则 tracing 保持关闭，Prometheus 仍可 scrape。

关键 span：

• http.request、ws.session
• voice.turn（一轮对话；单独成 trace，用 link 关联会话，避免要等 WebSocket 断开才在 Tempo 里看见）
• tool.schedule_query / tool.schedule_create / tool.schedule_update / …（保持调用顺序）
• asr.* / llm.* / tts.* 以及 db.select / db.update 等

span 属性只保留有界字段（阶段名、状态、耗时、token 计数），不写 transcript、session id、日程标题、坐标、凭证。

埋点位置（不改业务）

• Gateway HTTP / WebSocket：中间件与会话生命周期
• Intelligence Agent / 工具：通过 VoiceTelemetry 端口记录 turn / tool，Prometheus 与 Tempo 实现放在 infrastructure
• 外部 SDK：ASR、LLM、TTS、maps、realtime 共用 outbound call 计时
• SQLAlchemy engine：语句类型 + 连接池

效果

Grafana 把上面两类数据画出来即可，本身不是交付物。

Overview + HTTP（QPS、延迟、连接数、依赖就绪）：

WebSocket + Voice / tools（音频积压、语音阶段 p95、工具调用）：

External / database（外部依赖 QPS、TTFB、DB、LLM tokens）：

Traces（Tempo）：Recent voice turns / Recent tool calls：

单轮 voice.turn 瀑布图（ASR / LLM / tool / DB 嵌套耗时）：

验收标准

• GET /metrics 返回 Prometheus text，且不把 /metrics 自己算进业务 HTTP QPS。
• 指标能覆盖 HTTP、WebSocket、语音阶段、工具调用、外部依赖、数据库连接池；Grafana 折线图能画出 QPS / p95 / 连接数。
• 配置 OTLP endpoint 后，Tempo 能看到 voice.turn、工具 span，以及 ASR/LLM/TTS、DB 的子 span；Grafana Trace 表能列出最近对话轮次和工具调用。
• 一轮对话结束后，对应 voice.turn 立刻可查，不必等 WebSocket 断开。
• 指标 label 与 span attribute 不含 transcript、session id、坐标、凭证或异常原文。
• 现有后端单测与可观测性单测通过；鉴权、快照、提醒、语音对话行为与埋点前一致。

不做

• 不改 ASR / LLM / TTS、日程工具或 HTTP API 的业务语义。
• 不把 Grafana / Prometheus / Tempo 的部署与看板 JSON 当成这次后端 PR 的主体（它们只是看数）。
• 不做告警规则、SLO 合同、前端埋点或日志平台替换。
• 不把用户内容或密钥写入指标、trace 或 /metrics。