S51：用 JSONL 建立最小 Correlated Telemetry

内容类型：预习教材（不代表已完成）
日期：2027-01-12
阶段：P2 · AI Systems Engineering 90
总路线：Day 141 / 360
周次：W8 · Observability、Cost、SLO、Capacity
节奏：周二最小实现
状态：教材已备；学习未完成
标签：jsonl、correlation、telemetry、event-schema、aggregation

一句话定义

最小 telemetry 不需要先部署观测平台：一组结构稳定、可关联、可脱敏的 JSONL 事件已经足以学习事件模型、因果链和聚合边界。

学习目标

1. 能设计一个小型 telemetry event schema，区分通用 envelope 与事件属性。
2. 用 correlation/workflow id 聚合跨步骤事件，同时保留 attempt 与 causation。
3. 理解 append-only 记录、晚到事件和重复事件对聚合的影响。
4. 在最小练习中贯彻数据最小化，不记录敏感正文。

核心知识

• JSONL 每行一条独立 JSON，便于追加、流式读取和局部故障隔离；它不是生产存储保证，但适合本地教学。
• 通用字段可包含 timestamp、eventName、workflowId、traceId、spanId、causationId、attempt、bundleVersion、durationMs、outcome。
• 事件名应描述事实，例如 tool.call.completed，而不是模糊的 log。属性按语义命名并说明单位。
• Correlation 聚合不等于排序。客户端时间可能漂移，异步事件可能迟到；可同时保存 event time、ingest time 和序列/版本线索。
• 重试产生新的 attempt/span，但仍属于同一业务 workflow；把重试覆盖原记录会丢失成本和故障证据。
• Telemetry schema 也需版本。读取端应能处理旧行、未知字段和损坏行，并报告而非静默丢弃。

机制与推导

最小事件示例：

{"schemaVersion":"1","timestamp":"...","eventName":"model.call.completed","workflowId":"wf-1","traceId":"tr-1","spanId":"sp-2","attempt":1,"modelRef":"model@v3","inputTokens":120,"outputTokens":40,"durationMs":830,"outcome":"ok"}

聚合流程是 read line→parse→validate minimal fields→dedupe by event id if present→group by workflowId→sort with caution→derive facts。派生总时长不能简单把所有 span duration 相加，因为 span 可能并行；端到端时间可用 workflow 开始/结束，资源占用则按各操作求和。

若 event time 为 (t_e)、ingest time 为 (t_i)，迟到量 (L=t_i-t_e)。迟到事件可能改变先前窗口统计，因此本地聚合也应标注“截至 ingest time 的视图”。

最小练习或观察步骤

1. 手写 6～10 条合成事件：请求开始、模型调用、工具两次尝试、人工等待、任务完成。
2. 不放客户、prompt 或案件正文，只用合成 ID 和数值。
3. 用 Node/TS 或手工表按 workflowId 聚合事件，保留两个 attempts。
4. 计算调用次数、累计 token、已知工具错误与端到端时间。
5. 加一条迟到事件和一条损坏 JSON，写明读取策略。
6. 若未执行脚本，只保留示例和预期逻辑，不填写实际输出。

常见误区与边界

• 把所有事件按 timestamp 排序就宣称获得真实因果顺序。
• 重试覆盖旧 span，成本和失败原因消失。
• 将 span duration 相加当端到端延迟，忽略并行与等待。
• 高基数业务 ID 直接成为 metric label，导致成本与性能问题。
• JSONL 文件进入仓库却包含 secret 或真实敏感正文。
• 本地文件练习不具备生产收集、可靠传输、保留与访问控制能力。

系统 / 金融 / Web3 场景连接

金融案例可用合成 workflow id 串起模型、规则、工具和人工决定，真实案件 ID 应做受控映射或 tokenization。Web3 trace 可记录 chainId、RPC、method、block number 和交易阶段，但私钥、签名材料和完整敏感 calldata 不应进入普通日志。

自检问题

1. workflowId、traceId、spanId 和 causationId 各有什么作用？
2. 为什么端到端时间不能总用 span duration 之和？
3. 晚到事件会怎样改变窗口统计？
4. JSONL 教学实现缺少哪些生产保证？

专业课程对齐

• 阅读 OpenTelemetry 官方文档 的 context、trace/span、events 与 semantic conventions，重点映射层级 ID 和属性命名。
• 阅读 CloudEvents 官方站点 的通用事件属性，比较事件 envelope 与 OTel span event 的用途，避免把两种层次混为一谈。
• 阅读 Google SRE 资源 中 monitoring distributed systems 的章节入口，关注日志/指标应该支持哪些故障问题，而不是追求记录一切。

深入学习提示

先写三个要回答的问题，再决定字段。深入时用一条迟到事件、一条重复事件和一个并行 span 反例攻击聚合逻辑。若想扩展，只添加 schema version 与损坏行计数，不要把最小练习升级为完整 collector。

学后填写区

• 实际使用的事件 schema：
• 聚合与派生事实：
• 迟到 / 重复 / 损坏处理：
• 数据最小化措施：
• 未实际运行部分：