# 应用日志与中央观测接入规范

- 状态：已实施并通过中央 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` 中维护。