shay7sev
a875fe9f63
Emit correlated JSON logs from the API and FunASR services, propagate request IDs to the client, and configure bounded opt-in Docker logging. Document the host-wide Grafana/Loki query workflow and keep observability deployment ownership outside the application repository.
86 lines
3.5 KiB
Markdown
86 lines
3.5 KiB
Markdown
# 应用日志与中央观测接入规范
|
||
|
||
- 状态：已实施并通过中央 Loki 查询验收
|
||
- 实施日期：2026-07-22
|
||
- 应用：`teaching-feedback`
|
||
- 业务入口：`http://192.168.193.237:39180`
|
||
- 中央 Grafana：`http://192.168.193.237:39300`
|
||
- 中央栈目录：`/home/shay/data/docker-service/observability`
|
||
|
||
## 职责边界
|
||
|
||
本项目只负责应用日志质量和接入声明，不包含 Loki、Alloy 或 Grafana 的 Compose、凭据、
|
||
provisioning、数据卷和备份配置。中央栈由宿主机独立管理，停止或升级中央栈不得影响 API、
|
||
FunASR 或数据库迁移。
|
||
|
||
应用侧职责：
|
||
|
||
1. API 和 FunASR 向标准输出、标准错误写结构化 JSON 日志。
|
||
2. 容器提供稳定的应用、环境和版本标签，并限制 Docker 本地日志占用。
|
||
3. HTTP 请求返回并记录 `X-Request-ID`，异步转录记录可关联的业务 ID。
|
||
4. 日志不得包含凭据、请求正文、反馈正文、转录文本、音频路径或学生个人信息。
|
||
5. 中央栈不可用时，应用继续提供业务服务。
|
||
|
||
## 容器接入
|
||
|
||
生产 Compose 中的所有业务服务使用以下公共配置：
|
||
|
||
```yaml
|
||
x-default-logging: &default-logging
|
||
driver: local
|
||
options:
|
||
max-size: "20m"
|
||
max-file: "5"
|
||
|
||
x-observability-labels: &observability-labels
|
||
observability.logs: "true"
|
||
observability.application: "teaching-feedback"
|
||
observability.environment: "lan"
|
||
```
|
||
|
||
每个服务引用 `labels: *observability-labels` 和 `logging: *default-logging`。Docker 标签和日志
|
||
驱动只在创建容器时生效；仅修改这些字段时使用 `--force-recreate --no-build`，不需要重建镜像。
|
||
|
||
## JSON 日志字段
|
||
|
||
所有事件应包含：
|
||
|
||
- `timestamp`：UTC RFC 3339 时间。
|
||
- `level`：`TRACE`、`DEBUG`、`INFO`、`WARN` 或 `ERROR`。
|
||
- `service`、`environment`、`app_version`、`git_sha`。
|
||
- `event`：稳定的机器可查询事件名。
|
||
- `request_id`：HTTP 请求关联 ID；客户端传入合法值时继续传播，否则生成 UUID。
|
||
|
||
按业务阶段补充 `feedback_session_id`、`lesson_id`、`segment_id`、`worker_id`、`status`、
|
||
`latency_ms` 和 `error_class`。这些高基数字段保留在 JSON 正文中，不能设置为 Loki 标签。
|
||
|
||
允许作为 Loki 标签的字段仅限 `application`、`environment`、`compose_project`、
|
||
`compose_service`、`service`、`container`、`level`、`app_version` 和固定宿主机标识。
|
||
|
||
## 脱敏要求
|
||
|
||
禁止记录：
|
||
|
||
- `Authorization`、Cookie、Token、API Key、数据库连接串和密码。
|
||
- 请求体、反馈正文、总结内容、转录文本和热词正文。
|
||
- 音频内容、临时文件路径和包含学生身份的文件名。
|
||
- 学生姓名、联系方式、微信身份和其他个人信息。
|
||
|
||
失败事件记录稳定的 `error_class`、关联 ID 和耗时，不直接输出第三方异常对象或原始响应。
|
||
|
||
## 验收标准
|
||
|
||
发布后至少完成以下检查：
|
||
|
||
1. API 与 FunASR 容器健康，日志驱动为 `local/20m/5`。
|
||
2. 容器包含 `observability.logs=true`、`application=teaching-feedback` 和 `environment=lan`。
|
||
3. Grafana/Loki 可按 `application`、`service`、版本和时间筛选日志。
|
||
4. 一次 HTTP 请求的请求头、响应头和 JSON 日志使用同一 `request_id`。
|
||
5. API 与 FunASR 的异步事件可通过 `segment_id` 等字段关联。
|
||
6. 查询结果不包含上述敏感数据。
|
||
7. 中央栈停止时，`GET /health` 仍然成功。
|
||
|
||
具体查询与故障定位步骤见 `docs/observability-runbook.md`。中央栈运维只在
|
||
`/home/shay/data/docker-service/observability/README.md` 中维护。
|
||
|