53e0065e3e
配置 SSOT（TOML + .env） 统一错误契约 Auth 与事务边界 Redis / Celery 可靠性:业务 Redis（DB/0）与 Celery broker/backend（DB/1）显式拆分；连接池、sync client 可观测性（OpenTelemetry + LGTM）
82 lines
3.8 KiB
Markdown
82 lines
3.8 KiB
Markdown
# 可观测性（OpenTelemetry + Grafana LGTM）
|
||
|
||
本地开发使用 **OpenTelemetry** 采集 traces / metrics / logs，经 **OTel Collector** 写入 **Tempo / Prometheus / Loki**，在 **Grafana** 统一查看。
|
||
|
||
配置 SSOT：**[`config/default.toml`](../config/default.toml)** + **`config/{APP_ENV}.toml`** 的 `[deploy]` section（`otel_enabled`、`otel_exporter_otlp_endpoint`）。密钥与 `APP_ENV` 仍在 `.env`。
|
||
|
||
## 启动栈
|
||
|
||
在 `api/` 目录：
|
||
|
||
```bash
|
||
# 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）中：
|
||
|
||
```toml
|
||
[deploy]
|
||
otel_enabled = true
|
||
otel_exporter_otlp_endpoint = "http://localhost:48317"
|
||
```
|
||
|
||
推荐与全栈一并启动（`./development.sh` 在 TOML 中 `deploy.otel_enabled=true` 时会起 observability compose，并默认打开 Grafana 浏览器标签）：
|
||
|
||
```bash
|
||
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`](configuration.md)。
|
||
|
||
## 排查
|
||
|
||
1. **Grafana 无数据**：确认 `./development.sh` 日志含「启动可观测性栈」，或手动 `docker compose -f docker-compose.dev.yml -f docker-compose.observability.yml up -d`。
|
||
2. **应用报 UNAVAILABLE localhost:48317**：`deploy.otel_enabled=true` 但 Collector 未起 — 与 Grafana 问题同源。
|
||
3. **Prometheus 无 LLM 指标**： `./scripts/verify_observability_metrics.sh`（需 observability compose + 有流量）。
|
||
4. **Collector health**：`http://127.0.0.1:48333`；Prometheus target `otel-collector:8889` 应为 UP。
|
||
5. **Celery 任务失败/延迟**：Grafana → **Life Echo Business**（`memory.compaction.*`、`memoir` 等业务 span）；生产栈另可开 Flower `http://127.0.0.1:5555`（需 `FLOWER_PASSWORD`）。
|
||
6. **关闭 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`](configuration.md)。
|