Document how error codes line up with trace ids in the logging system.

Callers can follow one request from the HTTP envelope into the log collector without coupling the two modules. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-29 13:51:57 +00:00
parent bd53e9ba79
commit b67696d393
2 changed files with 14 additions and 0 deletions
@@ -0,0 +1,13 @@
+# 错误码、日志与 trace_id
+
+错误码仓库与日志仓库互不导入。对齐方式、调用顺序和查询命令见同级仓库 Logging-System 的 `docs/integration.md`。两个仓库需要放在同级目录时，可运行示例是 `Logging-System/examples/trace`。
+
+本地副本要点：
+
+1. HTTP 层回显 `X-Trace-Id`（`httpx.Trace`）。
+2. 用 `errcode.Wrap` 带上规范码；未知码回落 `sys.unknown_code`。
+3. `httpx.WriteError` 的信封带 `code` 和 `trace_id`。
+4. 同一 context 上的日志会带同一个 `trace_id`。若错误实现了 `ErrorCode()` / `ErrorFields()`，日志条目同时带上码和字段。
+5. 用 `trace_id` 到采集器查这一次调用，用 `code` 查同一类失败。
+
+副作用为 `possible` 或 `unknown` 的码禁止无条件重放。agent-native 与 agent-squad 的现有字符串如何落到规范码，见 [agent-native-mapping.md](agent-native-mapping.md) 与 [agent-squad-mapping.md](agent-squad-mapping.md)。