life-echo/api/docs/observability.md

# 可观测性（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)。