# GenAI observability and recovery kit

本入口按风险选择实验，而不是一次运行全部 11 个场景。先建立 trace 与稳定身份合同，再增加真实 SDK 链路，最后只运行目标存储和故障模型需要的恢复实验。

## 选择矩阵

| 风险                              | 模块入口                                  | 测试命令                             | 环境副作用                               |
| --------------------------------- | ----------------------------------------- | ------------------------------------ | ---------------------------------------- |
| trace 结构、隐私、token、业务终态 | `labs/genai-trace-contract/README.md`     | `npm run lab:trace:test`             | 无 Docker                                |
| SDK -> Collector -> Jaeger        | `labs/genai-otel-integration/README.md`   | `npm run lab:otel-integration:test`  | 测试使用受控 fixture；run 会重建 Compose |
| 进程崩溃恢复                      | `labs/otel-persistent-recovery/README.md` | `npm run lab:otel-recovery:test`     | run 操作专用容器与 volume                |
| 队列容量与拒绝重放                | `labs/otel-queue-saturation/README.md`    | `npm run lab:otel-saturation:test`   | run 操作专用容器与 volume                |
| commit 后响应丢失                 | `labs/otel-commit-ambiguity/README.md`    | `npm run lab:otel-ambiguity:test`    | run 启动故障代理                         |
| HTTP 200 partial success          | `labs/otel-partial-success/README.md`     | `npm run lab:otel-partial:test`      | run 启动部分提交代理                     |
| 排空速率与文件增长                | `labs/otel-drain-rate/README.md`          | `npm run lab:otel-drain:test`        | run 创建积压与专用 volume                |
| bbolt max_size                    | `labs/otel-storage-full/README.md`        | `npm run lab:otel-storage-full:test` | run 写满专用存储                         |
| 真实 ENOSPC                       | `labs/otel-enospc-recovery/README.md`     | `npm run lab:otel-enospc:test`       | run 使用专用 tmpfs                       |
| 只读恢复                          | `labs/otel-readonly-storage/README.md`    | `npm run lab:otel-readonly:test`     | run 变更专用 volume 挂载模式             |
| 运行期 EIO                        | `labs/otel-runtime-eio/README.md`         | `npm run lab:otel-eio:test`          | run 需要 privileged device-mapper        |

## 复用合同

调用方需要固定镜像 digest、Collector 配置、稳定 trace/span ID、payload hash、端口和故障窗口。输出必须同时包含 Collector 接收/拒绝/发送状态、queue/storage 证据和 Jaeger 最终 unique/duplicate/missing 查询。

`:run` 命令会修改本机 Docker 运行态；执行前阅读对应 README，确认端口、Compose project、volume、tmpfs 或 loop device 只属于本实验。单机恢复结果不能外推为节点丢失或长期生产可靠性。