Files

shay7sev a875fe9f63 feat(observability): add structured application logging

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.

2026-07-22 13:52:40 +08:00

3.5 KiB

Raw Blame History

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

状态：已实施并通过中央 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 或数据库迁移。

应用侧职责：

API 和 FunASR 向标准输出、标准错误写结构化 JSON 日志。
容器提供稳定的应用、环境和版本标签，并限制 Docker 本地日志占用。
HTTP 请求返回并记录 X-Request-ID，异步转录记录可关联的业务 ID。
日志不得包含凭据、请求正文、反馈正文、转录文本、音频路径或学生个人信息。
中央栈不可用时，应用继续提供业务服务。

容器接入

生产 Compose 中的所有业务服务使用以下公共配置：

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 和耗时，不直接输出第三方异常对象或原始响应。

验收标准

发布后至少完成以下检查：

API 与 FunASR 容器健康，日志驱动为 local/20m/5。
容器包含 observability.logs=true、application=teaching-feedback 和 environment=lan。
Grafana/Loki 可按 application、service、版本和时间筛选日志。
一次 HTTP 请求的请求头、响应头和 JSON 日志使用同一 request_id。
API 与 FunASR 的异步事件可通过 segment_id 等字段关联。
查询结果不包含上述敏感数据。
中央栈停止时，GET /health 仍然成功。

具体查询与故障定位步骤见 docs/observability-runbook.md。中央栈运维只在 /home/shay/data/docker-service/observability/README.md 中维护。

3.5 KiB Raw Blame History Unescape Escape