可观测性

1.从 API 返回值精确提取 token 数：不要用 len(content)/1.5 估算，误差 30%+

2.区分 4 种 token 类型：input/output/cache_read/cache_write 各有不同计费规则

3.适配多提供商差异：OpenAI 无 cache_write，Anthropic 有完整 4 种，需统一数据结构

4.结构化日志 + JSON 持久化：便于程序化分析成本分布和性能瓶颈

5.子 Agent 日志隔离：多 Agent 系统中每个子 Agent 的日志在独立 session 中

6.持仓日志用全量快照而非增量：每条记录包含完整 positions，任意行可独立恢复状态

7.操作 id 单调递增：保证操作序列可追溯，支持并发场景下的顺序判定

8.fcntl 文件锁保护并行写入：多 Agent 共享 position.jsonl 时防止数据交错

9.滚动指标设最小观测窗口：小时级 min_periods=10，日线 min_periods=3，避免早期极端值

10.WebSocket 广播前检查 readyState：避免向已断开的客户端发送数据导致异常

11.LLM trace 用 content.length/4 粗估 token 数：不依赖 tiktoken 库，适合轻量级场景

12.JSONL 持久化白名单而非黑名单：新增事件类型默认不持久化，避免意外 I/O 膨胀

13.MCP 协议暴露调试接口：比自定义 HTTP API 更标准化，外部 Agent 可直接接入

14.JSONL 尾部读取时跳过截断的第一行：offset > 0 时 slice(firstNewline + 1) 避免 JSON.parse 失败

15.costUSD 和 estimatedCostUsd 互斥累加：同一行只取一个，避免双重计费

16.Rate limit 时延长缓存 TTL 而非重试：GitHub API 限流是小时级重置，频繁重试浪费配额

17.反向读取 Buffer 拼接后再 toString：避免在多字节 UTF-8 字符中间截断导致乱码

18.被动观测优于主动注入：读 Agent 原生日志文件而非注入 SDK，零侵入零耦合

19.注意力分级按 ROI 排序：merge（一键完成）> respond（快速解锁）> review（需调查），人类行动成本递增

20.cost 字段优先级链：costUSD > estimatedCostUsd > token 估算，避免双重计数

21.enrichment 超时隔离：metadata enrichment 3s + PR enrichment 4s 独立超时，互不阻塞

22.check() 返回可操作的错误信息：每个 off/warn 状态附带具体安装命令，用户无需查文档

23.Config 双源加载：YAML 文件优先 + 环境变量回退，适配容器和 CI 场景

24.配置保存时自动 chmod 600：防止含密钥的配置文件被其他用户读取

25.流式响应包装器模式：用 _trace_async_generator_wrapper 包装 AsyncGenerator，在 finally 块中统一提取最后 chunk 的 usage，避免每个 chunk 都创建子 span

26.装饰器 end_on_exit=False：手动控制 span 生命周期，适配流式响应和异步场景

27.Lazy import OTel SDK：在 setup_tracing 时才导入 OpenTelemetry 库，避免未启用追踪时的启动开销

28.None 值过滤：span 属性字典用 {k: v for k, v in attrs.items() if v is not None} 过滤，避免 None 值污染

29.GenAI 语义属性命名：使用 gen_ai.request.model、gen_ai.usage.input_tokens 等标准属性名，而非自定义字段

30.Provider 包装器用 __getattr__ 代理非核心方法，保持接口透明

31.三层 JSONL 分离关注点：日级快照查趋势、任务级明细查归因、完成记录查进度

32.生存状态机将连续余额映射为离散状态，简化 Agent 决策和 UI 展示

33.评估门控阈值在后端和前端用同名常量定义，防止不一致

34.LangSmith 项目 URL 使用模块级缓存避免重复网络请求

35.异步 URL 解析用 asyncio.to_thread + 超时保护不阻塞 TUI 事件循环

36.评估场景用确定性 UUID 关联 instruction 到 LangSmith example 支持跨实验对比

37.Harbor feedback 写入前检查已有 feedback 避免重复

38.LLM 日志用 min_response_length 过滤短回复噪声：避免记录确认类短响应

39.操作历史暴露为 MCP 工具：让 Agent 可以自省操作记录辅助决策

40.进度回调用闭包工厂：捕获 task 引用，避免在工作流函数间传递状态

41.JSONL 追加写入天然崩溃安全：进程中断不丢失已写入的日志行

42.setup_logging 使用 force=True 防止多模块重复添加 handler

43.日志路径用 Path.resolve() + startswith() 防目录穿越

44.开发模式 monkey-patch watchfiles 排除 logs/ 目录避免热重载循环

45.在 Model Factory 层注入 Tracer：一处修改覆盖所有模型调用，零侵入业务代码

46.Tracer 附加用 try/except 降级：追踪是辅助能力，失败不应阻断核心功能

47.子 Agent 日志统一 [trace=xxx] 前缀：便于日志聚合工具按 trace_id 关联父子调用链

48.并发子 Agent 数量硬限制 [2,4]：防止 LLM 生成过多并行调用导致资源耗尽

49.Factory 层注入 Tracer 实现零侵入追踪：所有模型实例自动获得追踪能力，无需业务代码修改

50.双重检查锁保证多 Worker 下配置单例安全：避免 Gunicorn prefork 模式下重复初始化

51.Run Metadata 标签选择 3-5 个高价值维度：过多标签增加存储成本且降低筛选效率

52.每轮迭代即时记录五维指标而非事后汇总：便于实时监控和中途干预

53.用 ROI(confidence_gain/lines_added*1000) 量化每轮投入产出比：将继续/停止决策数据化

54.tiktoken 计数时设 disallowed_special=() 避免非英文文本中特殊 token 字符串导致计数失败

55.max_tokens 参数降级兼容：先尝试 max_tokens，BadRequestError 时回退 max_completion_tokens

56.用 @lru_cache 缓存 logger 实例 + handlers.clear() 保证幂等：避免多模块重复初始化导致日志重复

57.ContextVar 实现请求级事件 sink 隔离：GUI 和 CLI 可注册不同回调互不干扰

58.developer_mode 开关控制错误详情级别：开发环境输出完整 traceback，生产环境返回结构化摘要

59.阶段差值成本归属：记录阶段开始前的累计成本，结束后取差值，实现无侵入的阶段级成本拆分

60.LangSmith 零代码集成：仅通过环境变量启用外部追踪，不在业务代码中引入 Tracer 依赖

61.Rich Progress 用 transient=True 避免完成后进度条残留污染终端历史

62.批量 AI 调用失败时设 score=0 降级而非中断，保证进度条完整推进

63.Emoji 阶段标记比 [INFO] 前缀更利于人眼快速扫描定位当前阶段

64.环境变量驱动零配置激活：设了对应环境变量就启用 Tracer，不设就静默跳过，无需配置文件

65.懒加载 import 防止启动失败：每个 Tracer 的 SDK import 放在工厂函数内，未安装不影响其他 Tracer

66.asyncio.Queue 单 worker 串行化：避免多 Tracer 并发写入的竞态，同时不阻塞 DAG 主路径

67.ready 属性双重门控：__init__ 中检测可用性设 ready，所有方法入口检查 ready 后静默返回

68.独立 TracerProvider 避免全局污染：多 OTel 后端共存时各自创建 provider，不覆盖全局

69.Langfuse 零侵入集成：通过 import 层面替换 AsyncOpenAI 而非手动注入 tracer，业务代码零修改

70.双层统计互补：TokenTracker 统计精确 token（API 层），statistic_data 统计调用计数（缓存层），两者覆盖不同维度

71.流式响应从最后一个 chunk 提取 usage：OpenAI 流式 API 在最终 chunk 携带 usage 信息，需累积到流结束后统计

72.日志路径过滤器：用 logging.Filter 子类过滤 /health 等高频路径的 200 响应，保持日志信噪比

73.指标函数纯函数化：metrics.py 只暴露 task_enqueued/task_dequeued 等纯函数，不依赖任何业务类实例

74.事件日志 fire-and-forget：emit_monitor_event 外层 try-except 吞掉所有异常，可观测性永远不影响主流程

75.TimingSpan 继承 ContextDecorator：同时支持 @decorator 和 with 语句两种埋点方式，覆盖函数级和代码片段级

76.线程池健康检查双级检测：先检查单个任务是否超时，再检查线程池整体活跃度，避免误判

77.用 Pydantic BaseModel 作为 CostManager 基类：天然获得 JSON 序列化、字段验证、类型安全

78.pricing_plan 与 model 分离：同一模型在不同渠道（直连 vs OpenRouter）价格不同，用 pricing_plan 覆盖

79.流式 usage 三源适配：chunk.usage → choice.usage → 本地 tiktoken 计算，逐级降级

80.loguru 配置三步法：remove() 清除默认 → add(stderr, level) 统一入口 → 环境变量控制级别

81.吞吐量优于延迟：批处理场景用 items/s 而非 p99 延迟衡量性能

82.决策日志标注来源：自适应参数选择时明确标注 (from env) 或 (auto, resource=X) 便于排查

83.健康端点含业务指标：/health 不仅返回存活状态，还包含队列统计等业务健康信息

84.用 Cargo feature flag 而非运行时 if 门控指标代码：编译期零开销

85.指标常量集中定义在独立 crate 的 definitions.rs：IDE 可跳转，避免拼写错误

86.直方图桶按子系统定制：LLM 调用和 HTTP 请求的延迟分布差异巨大

87.SQLite 持久化用单连接池 + WAL 模式：低吞吐场景避免锁竞争

88.采集循环通过 mpsc channel 异步写入 DB：不阻塞 10s 采集节奏

89.JSONL 追加写入保证崩溃安全：appendFileSync 写到哪算哪，不丢数据

90.延迟统计设上限阈值（如 12h）：过滤跨 session 的异常值避免 p95 失真

91.诊断 session 状态用 TTL+LRU 淘汰：防止长期运行的 daemon 内存泄漏

92.成本估算建立回退链：API 返回值 → 配置价格表 → 记录 missing 计数

93.为所有外部 API 调用统一添加 @traceable 装饰器，而非只追踪 LLM 调用

94.使用 langsmith:nostream tag 避免流式追踪产生碎片化 span，保证完整请求/响应对

95.aevaluate 的 metadata 应记录所有影响结果的配置参数（模型+行为+搜索），确保实验可复现

96.pairwise 对比评估必须 randomize_order=True 消除 LLM 裁判的位置偏差

97.emoji 前缀日志分类：用 ✨🛠️🔧🎯 等 emoji 标记 Agent 思考/选择/执行/完成，大量日志中快速定位

98.Token 限额异常不重试：TokenLimitExceeded 是确定性错误，排除在 retry 列表外避免无意义重试

99.tiktoken fallback 策略：未知模型名时降级到 cl100k_base 编码，避免初始化失败

100.Observer 三方法契约分离：get_status_table/is_healthy/has_errors 各司其职，is_healthy 和 has_errors 语义独立

101.聚合健康用 all() 短路：任一组件不健康即系统不健康，避免复杂加权

102.tabulate 表格化输出：CLI 和日志场景下比 JSON 可读性高，且自带对齐

103.用 LangfuseSpanProcessor.shouldExportSpan 在 SDK 层过滤，比 Langfuse 后端过滤更高效

104.SecurityFilter 默认开启 enableDataMasking，opt-out 比 opt-in 更安全

105.EXCLUDED_SCOPES 用 Set 而非 Array，O(1) 查找避免高频 span 的性能损耗

106.FilteredLangfuseCallbackHandler 继承官方 Handler 只 override 需要过滤的方法，最小化维护成本

107.按功能维度拆分 token 计数器：不同操作的 token 消耗模式不同，全局统计无法指导优化

108.Pino multistream 一写多读：同一事件同时写入 JSONL（机器分析）和 pretty log（人工调试）

109.装饰器零开销关闭：CONFIG_DIR 为空时直接返回原方法引用，无任何运行时包装

110.共享 Pino 实例避免 worker thread 泄漏：静态 sharedPinoLogger 防止高并发场景内存膨胀

111.Pino mixin 自动注入 span 上下文：避免手动传递 context 参数穿透多层调用栈

112.双路回调注入：LLM 构造函数注入追踪 LLM 事件，graph config 注入追踪工具事件，缺一不可

113.被动拉取统计快照：UI 按自身刷新率调用 get_stats()，避免高频事件推送的复杂度

114.Token 显示优雅降级：provider 不返回 usage_metadata 时显示 -- 而非误导性的 0

115.后端延迟导入：在 if 分支内 import，未启用的后端不拖慢启动

116.指标计算与记录分离：纯函数计算指标，Tracking 类只负责广播，便于单元测试

117.斜杠分层命名空间：critic/score/mean 格式让 wandb/tensorboard 自动按前缀分组

118.环境变量控制调试追踪开关：VERL_ENABLE_TRACKER 默认关闭，生产环境零开销

119.注意力路由按 ROI 排序：merge 一键完成最高，respond 快速解锁次之，working 不打扰最低

120.JSONL 尾部读取跳过首行：从文件中间开始读时第一行必然截断，必须丢弃

121.rate limit 时延长缓存而非重试：避免限流雪崩，同时在 UI 标记数据可能过期

122.双轨活跃度检测互补：终端正则快但粗，JSONL 类型推断慢但准，组合使用覆盖更全

123.环境变量驱动开关：`Enabled()` 纯环境变量检查，未设置时 `Init()` 只安装 no-op provider

124.Decorator 模式存储插桩：`WrapStorage()` 检查 `Enabled()` 后返回 decorator 或原始实例，零开销

125.AI token 从 API 返回值提取：`message.Usage.InputTokens`/`OutputTokens` 直接计量，不做估算

126.JSONL 文件权限 0644：audit trail 设计为可通过 git 共享，注释说明有意为之

127.PersistentPostRun 优雅关闭：5s 超时 `telemetry.Shutdown()` 确保 CLI 进程退出前 flush 完毕

128.Logger 懒初始化避免循环依赖：构造时不读配置，首次 log 时才初始化文件路径

129.语义化日志方法（dataIn/dataOut/success/failure/timing）比纯级别更易 grep 过滤

130.appendFileSync 同步写入保证崩溃前日志不丢失，stderr 作为最后回退

131.进程注册表用事件驱动（exit 回调）而非轮询，实时感知子进程退出

132.Token 按 5 种类型独立计数（input/output/thought/cache/tool），不同类型计费规则不同

133.CLI 遥测默认关闭且不初始化 SDK，确保无遥测需求时零性能开销

134.一键部署脚本封装 Jaeger + OTEL Collector 的下载/启动/配置/退出清理全流程

135.sessionId 作为公共属性贯穿所有日志和指标，实现单会话全链路关联

136.文件操作指标记录 MIME 类型和行数，支持按文件类型分析 Agent 行为模式

137.LLM 客户端统一返回 (pure_result, raw_response) 元组：wrapper 从 raw_response 提取 usage 而不侵入业务返回值

138.frozen dataclass 传递观测数据：拦截器收到的 Context/View/Usage 不可篡改，天然线程安全

139.Handle 模式管理拦截器生命周期：register 返回 Handle，dispose() 移除，避免忘记清理导致内存泄漏

140.依赖注入解决 registry↔store 循环引用：模块加载时注入读写函数而非直接 import

141.三层模型限制查找保证未知模型安全运行：缓存→静态表→保守默认值，宁可多分批也不撞限制

142.批次级容错统计而非全有全无：返回 failedBatches/totalBatches 让调用方决定是否接受部分结果

143.用 DummyXxx 鸭子类型替代条件判断：DummyWandb/DummyReport/print0 三重模式消除日志代码中的 if 分支

144.未知 GPU 返回 inf 而非抛异常：MFU 显示 0% 比中断训练更安全

145.wandb log 始终包含 step + total_training_flops 双 x 轴：支持按步数或按计算量对齐不同实验

146.bpb 替代 loss 作为评估指标：消除 vocab size 对损失值的影响，跨 tokenizer 可比

147.训练前 10 步不计入 total_training_time：排除编译预热对 ETA 估算的干扰

148.多进程 Prometheus 用 TemporaryDirectory 自动管理生命周期，atexit 时 mark_process_dead

149.跨进程 trace 传播用 os.environ 注入 + context manager 恢复，比 IPC 简单可靠

150.推理指标按 1-2-5 序列构建直方图桶，覆盖 1 到 max_model_len 的完整范围

151.空闲引擎日志降级为 debug：检测连续两个周期吞吐为零时切换日志级别

152.MFU 用分析式公式计算而非运行时采样：按 Attention/FFN/Unembed 组件分别估算 FLOPs 和带宽

153.每个任务创建独立 Langfuse handler 并设 session_id=task_id：同一任务的所有 Agent trace 自动归组

154.ContextVar 注入 task_id 到日志：异步任务链中自动传播，无需手动传参

155.StepTimer 上下文管理器自动计时：with StepTimer(log, agent, action) 自动记录耗时和异常

156.Rich 彩色输出自动降级：try import Rich，失败则 fallback 到 StreamHandler，不强依赖

157.SSE 事件自动附加 UUID id + timestamp：便于前端去重和排序

158.用 RAII 包装计时采集：ScopedLatency 析构自动写入，防止异常路径遗漏 close

159.栈式路径追踪嵌套关系：vector<Stage> 模拟调用栈，自然表达父子阶段层级

160.双模式激活（debug 标志 OR trace_id）：本地调试和分布式追踪共用同一 Profiler