Honeycomb Tracing 是一个用于在 Honeycomb 中追踪 Paperclip 运行、请求与完整 CI 套件的技能。其目标是生成与实际运行或 CI 尝试绑定的可检查瀑布图，解释哪些时间区间主导了总耗时，并找出最小且有价值的下一个实验。技能要求尊重“仅诊断”的请求：追踪本身不授权重放任务、更改凭据或部署插桩。
选择数据路径
不同问题对应不同的起点：
- 任务在模型执行前、中、后为何缓慢：使用下文的应用工作流；若 span 缺失，先做运行时配置。
- 问题页面为何加载缓慢：结合请求 span 与浏览器计时。
- 哪些 CI 作业或测试文件拖慢了整个套件：使用 CI 性能分析。
- 新 span 应加在哪里：参考下文插桩指导与可观测性契约。
仓库相对路径与命令均以检出根目录为基准。维护中的契约文件是 doc/observability.md 和 doc/ci-profiling.md；当部署版本与文档不一致时，需重新核对它们及所属代码。
保持三种路径相互区分：
- 可观测性（Observability）：由运维配置的 OpenTelemetry 导出到 Honeycomb 或其他 OTLP 目标。未配置端点时，该追踪保持关闭。
- 遥测（Telemetry）：packages/shared/src/telemetry/ 下的一方事件，默认发送给 Paperclip，除非选择退出。新增这类事件需要生成的契约、Telemetry README 以及 AGENTS.md 中的隐私审查流程。
- 运行日志（Run log）：本地 heartbeat_run_events 与已测量的性能事件。适合用于关联分析，但本地事件不能证明已导出到 Honeycomb。
在封闭的 span 属性白名单内做可观测性改动，无需经过 Telemetry 隐私审查。必须保留端点门控与无操作行为。
定位应用的 trace
需要先确定实例、公司、问题、agent、运行 UUID 以及 UTC 时间区间。记录生效的 harness/model、工作区/仓库、热会话或新会话，以及实际部署的修订版本。任务标识符不是运行 UUID；一个任务可以有多次运行，一次运行也可以有多次执行尝试。
当已有 Honeycomb 工具被暴露且获得授权时，优先使用它们；否则使用已登录的浏览器。当前项目链接指向 team paperclip、environment test、dataset paperclip 以及 service.name = paperclip。这些是 ui/src/lib/honeycomb-run-link.ts 中的默认值，并不代表每次部署的目标都是如此。比较数据前需先验证目标。
运行页面上若有 View in Honeycomb 可直接打开。它需要 Paperclip Developer Mode 以及本地隐式的 board 或实例管理员访问权限。该链接只查询已有数据。Re-run with provider trace 是另一个动作：它会启动工作，读取 Honeycomb 并不需要它。
没有该链接时，可在本地计算相同的关联值：
先把 RUN_ID 设为实际保存的运行 UUID；不要有末尾换行参与哈希。
node -e 'console.log(require("node:crypto").createHash("sha256").update(process.argv[1]).digest("hex").slice(0, 12))' "$RUN_ID"
将 paperclip.task.run.run_id 过滤为该 12 位小写哈希，并将 service.name 过滤为观测到的服务。从该运行的绝对时间窗口开始。产品链接默认最近七天，对更早的运行需放宽窗口。按 trace.trace_id 分组 COUNT，以发现匹配的 trace。
产品的根过滤器为 name in [task.execution_attempt, task.provider_session, task.run]。使用 Honeycomb 的 in 操作符，不要自造 OR 分组。当设置失败或准备阶段 span 缺失时，移除 name 过滤器；较旧或独立的准备过程可能有单独的 trace ID。
打开每个相关 trace 及其 span 详情。仅统计数量的查询或导出无法确定 span 时长、父子关系或因果归属。需记录 trace URL、时间窗口、服务/版本，以及相关 span 名称与计时。
在近期调查中，运维人员 ~/.secrets 中的 HONEYCOMB_TEST_CONFIG_API_KEY 可读取元数据，但无法查询 trace。写入许可、元数据访问与查询访问是不同的。需要核实当前能力；查询不可用时，应使用已登录的 UI，而不是新建密钥或升级权限。只读取所需的密钥字段，绝不整体转储文件，并确保取值不出现在命令、制品、仓库文件和报告中。
正确解读时间线
各区间含义与下一步检查：
- 运行创建 → executor 启动：准入/排队延迟；检查 drain、容量和调度证据。
- task.execution_attempt：服务端 executor 调用，涵盖准备、派发、持久回复与清理。
- heartbeat.prepare.、native.controller.：控制器准备；展开工作区、配置、后端与运行时选择工作。
- task.provider_session：原生 provider 生命周期；包含准备与执行，在外层工作区持久化前结束。
- task.run：旧版适配器根。
- runner.session.startup、environment.、stage.、sandbox.*：runner/环境获取、工作区传输与启动。
- agent.turn：agent 轮次时间；在把全部时间称作模型延迟前，先检查实际子 span。
- execution.workspace_finalize、workspace_sync.、completion.、response.*：回拷、结算、响应持久化与发布工作。
attempt 与 provider 生命周期是相互链接的根，不一定共享同一 trace ID。两者都不保证在排队或重启之间形成一条连续 trace。需结合运行日志与已保存的回复时间戳进行关联。原生本地事件 task.run.measured 包含最终耗时与持久回拷。
使用开始/结束时间比较串行区间与并行工作的并集。绝不把父 span 与子 span 相加，也不要把并行分支求和当作总耗时。例如 configuration_skills 位于 execution_configuration 之内，skills.prepare 与更宽的 heartbeat.prepare_before_environment 重叠。详情 span 每个名称每次尝试上限为 16 个；缺少逐项子 span 不代表后续项没有工作。
区分首次流式文本、已提交回复、外部已送达消息与浏览器绘制。成功的 response.transaction.commit 证明持久存储；response.publish 是入队，execution.realtime 是服务端派发。二者都不证明用户看到了响应。选择用户要求改进的边界，然后测量到该边界的整条路径。
对于缓慢的问题页面，将 issue.read.<phase> 与 Server-Timing（paperclip_issue、issue_<phase>）以及浏览器的请求瀑布图与 issue-detail:navigate→content-paint 测量结合起来。并发读取相互重叠。API 快速完成不代表对话内容快速显示或渲染。
一个很长的父 span 没有子 span 是归因缺口。它不证明是 SQL、网络或模型时间。数据库假设使用 fix-slow-queries；CPU 假设使用覆盖实际慢阶段的有界授权剖析；排队期间取的样本无法解释准备阶段。容器聚合 CPU 低并不能排除 Node 主线程被阻塞。需将剖析诊断与未剖析的验收计时分开。
只补充缺失的插桩
编辑前阅读适用的仓库规则。复用已有的计时接缝：
- server/src/services/execution-preparation-timing.ts：withRunExecutionTiming、createRunPreparationTiming、measureRunPhase 与 beginRunPhase。复用已有 attempt，不要为每个详情新建根。
- server/src/services/native-runtime/native-run-trace.ts：原生生命周期层级及其与所属 attempt 的链接。
- server/src/services/issue-read-timing.ts：问题读取阶段与 Server-Timing。
- packages/adapter-utils/src/acpx-engine/startup-timing.ts：运行时父上下文与封闭 span 属性。适配器工具接收宿上下文，而不是自行构建独立导出器。
当缺失有意义的边界时，扩展封闭的阶段联合。包裹实际被 await 的操作，在异步/provider 边界之间保持父上下文，并在成功与失败时都结束 span。对操作之后记录的 span 保留真实墙钟时间。使用已有的哈希 ID、封闭枚举和允许的数值计数；不要添加提示词、工具参数/结果、路径、原始标识符、凭据或异常文本。不要为解释一次慢扫描而启用全部文件系统插桩。
可观测性不得重试操作、替换其返回/错误、更改授权/锁，或在追踪器失败时破坏执行。即使其他库注册了 OTel provider，也要保留根采样与显式端点门控。trace 契约变化时更新 doc/observability.md。针对端点关闭行为、父子关系/并发运行隔离、失败处理以及改动的接缝运行聚焦测试。只有拿到真实导出的证据，才能声称新 span 出现在 Honeycomb 中；仅单元测试追踪器不能证明写入成功。
比较并交回有用证据
选择最大的可操作串行等待或无法解释的缺口，然后在最小但忠实的层级复现。比较匹配的运行：相同 harness/model、工作区大小、会话热度、并发度及相关修订/配置。有多次运行时报告样本数与中位数/范围。保留失败；一次快速的失败运行不是延迟改进。
返回运行/尝试与 trace 链接、观测到的修订、端到端计时、主要的非重叠阶段、不确定性，以及下一步动作或已验证的收益。准确标注本地、合成与托管证据：开发主机复现不是本地检出运行，已合并的修复也不证明托管环境得到改进。若 trace 不可用，说明缺失的访问或覆盖范围，以及运行日志/浏览器测量实际能证明什么。
限制与前提
本技能不授权重放任务、更改凭据或部署插桩。它依赖 Honeycomb 与 OTLP 端点配置；未配置端点时追踪保持关闭。部分密钥可能只能读取元数据而无法查询 trace；查询不可用时应改用已登录 UI。功能、收费、价格、平台与效果等未在本资料中提供的信息暂未提供。