53e0065e3e
配置 SSOT（TOML + .env） 统一错误契约 Auth 与事务边界 Redis / Celery 可靠性:业务 Redis（DB/0）与 Celery broker/backend（DB/1）显式拆分；连接池、sync client 可观测性（OpenTelemetry + LGTM）
3.8 KiB
可观测性（OpenTelemetry + Grafana LGTM）
本地开发使用 OpenTelemetry 采集 traces / metrics / logs，经 OTel Collector 写入 Tempo / Prometheus / Loki，在 Grafana 统一查看。
配置 SSOT：config/default.toml + config/{APP_ENV}.toml 的 [deploy] section（otel_enabled、otel_exporter_otlp_endpoint）。密钥与 APP_ENV 仍在 .env。
启动栈
在 api/ 目录：
# 1. 数据库与 Redis
docker compose -f docker-compose.dev.yml up -d
# 2. 可观测性（需已存在 life-echo-dev 网络；端口来自 .env 或下列默认）
docker compose -f docker-compose.dev.yml -f docker-compose.observability.yml up -d
| 服务 | 默认宿主机地址 | compose 变量 |
|---|---|---|
| Grafana | http://127.0.0.1:48300 （admin / admin） | GRAFANA_HOST_PORT |
| Prometheus | http://127.0.0.1:49090 | PROMETHEUS_HOST_PORT |
| OTLP gRPC | http://127.0.0.1:48317 | OTEL_GRPC_HOST_PORT |
| OTLP HTTP | http://127.0.0.1:48318 | OTEL_HTTP_HOST_PORT |
| Collector health | http://127.0.0.1:48333 | OTEL_COLLECTOR_HEALTH_HOST_PORT |
容器内部仍使用标准端口（如 Collector 4317）；仅宿主机映射使用 48xxx 段，与 Postgres 48291、Redis 48307 同一风格。
预置 Dashboard（Life Echo 文件夹）：
| Dashboard | 用途 |
|---|---|
| Life Echo Overview | API RED、LLM 摘要、依赖延迟 |
| Life Echo LLM | call_type / agent / tokens、outcome 分布 |
| Life Echo Business | 回忆录阶段、WS/ASR/TTS、Celery 业务 span |
| Life Echo Logs | Loki 按 event / trace_id 检索 |
启用应用导出
在 config/development.toml（或对应环境 overlay）中：
[deploy]
otel_enabled = true
otel_exporter_otlp_endpoint = "http://localhost:48317"
推荐与全栈一并启动（./development.sh 在 TOML 中 deploy.otel_enabled=true 时会起 observability compose，并默认打开 Grafana 浏览器标签）：
cd api
./development.sh
若 API 跑在 Docker compose 里，应设 otel_exporter_otlp_endpoint = "http://otel-collector:4317"（服务名 + 容器内端口），见 config/staging.toml / config/production.toml。
不需要可观测性时：在对应 config/*.toml 设 otel_enabled = false（或未启动 observability compose）。
legacy：仍可在 .env 设 OTEL_ENABLED=true/false 覆盖 TOML，供 development.sh 决策是否启动 compose。
采样与其它 OTel 项
采样策略等在 [otel] section 与 OtelConfig.traces_sampler()（按 APP_ENV 推导），见 docs/configuration.md。
排查
- Grafana 无数据：确认
./development.sh日志含「启动可观测性栈」，或手动docker compose -f docker-compose.dev.yml -f docker-compose.observability.yml up -d。 - 应用报 UNAVAILABLE localhost:48317：
deploy.otel_enabled=true但 Collector 未起 — 与 Grafana 问题同源。 - Prometheus 无 LLM 指标：
./scripts/verify_observability_metrics.sh（需 observability compose + 有流量）。 - Collector health：
http://127.0.0.1:48333；Prometheus targetotel-collector:8889应为 UP。 - Celery 任务失败/延迟：Grafana → Life Echo Business（
memory.compaction.*、memoir等业务 span）；生产栈另可开 Flowerhttp://127.0.0.1:5555（需FLOWER_PASSWORD）。 - 关闭 telemetry：
config/*.toml→[deploy] otel_enabled = false。
Checklist（本地）
config/development.toml中deploy.otel_enabled=true./development.sh或 observability compose 已启动- API + Celery worker 在跑并产生请求
- Grafana http://127.0.0.1:48300 可打开
更多配置分层说明见 configuration.md。