telemetry@earendil-works/pi-telemetry

要点Key points

• 根入口只有 4 个值导出：defineTelemetrySchema、createTypedSpanStarter、NOOP_TELEMETRY_CONTEXT 与 InMemoryTelemetryContext，其余全是类型。The root has only 4 value exports — defineTelemetrySchema, createTypedSpanStarter, NOOP_TELEMETRY_CONTEXT and InMemoryTelemetryContext; everything else is a type.
• 没有运行时依赖：package.json 只有 @types/node 与 vitest 两个 devDependencies。No runtime dependencies: package.json has just two devDependencies, @types/node and vitest.
• 别和 coding-agent 的 core/telemetry.ts 混淆：那是“安装遥测”开关（PI_TELEMETRY 或设置项），与这个包无关。Don't confuse it with coding-agent's core/telemetry.ts: that is the install-telemetry switch (PI_TELEMETRY or a setting) and has nothing to do with this package.

工作原理How it works

1. 可选遥测：函数参数默认 telemetryContext = NOOP_TELEMETRY_CONTEXT，调用方想要时再传真实的上下文。Optional telemetry: default a parameter to telemetryContext = NOOP_TELEMETRY_CONTEXT and let callers pass a real context when they want one.
2. 测试：new InMemoryTelemetryContext()，跑被测代码，再断言 getSpans()。Tests: new InMemoryTelemetryContext(), run the code under test, then assert on getSpans().
3. 写适配器：实现 TelemetryContext，再用 ./testing 的 createTelemetryAdapterConformance() 验证。Writing an adapter: implement TelemetryContext, then verify it with createTelemetryAdapterConformance() from ./testing.

要点Key points

• 没有 end()：startSpan() 拥有结束时机，回调的返回值或 promise 落定时 span 才结束。There is no end(): startSpan() owns settlement, and the span ends when the callback's value or promise settles.
• 父子关系完全靠显式传参：把回调里的 span 传给下层代码。包里没有 AsyncLocalStorage。Parentage is purely explicit: pass the callback's span down to lower-level code. There is no AsyncLocalStorage in the package.
• span 是诊断数据而不是业务状态：记录与否不能改变操作是否执行、成功或失败。A span is diagnostic data, not business state: recording must not change whether an operation runs, succeeds or fails.

工作原理How it works

1. ctx.startSpan({ name, attributes }, async (span) => { … span.setAttributes({ found }) … })。ctx.startSpan({ name, attributes }, async (span) => { … span.setAttributes({ found }) … }).
2. 子 span：在回调里 span.startSpan({ name: 'child' }, …)。A child: span.startSpan({ name: 'child' }, …) inside the callback.
3. 预期失败（返回 { ok: false }）要显式 span.setStatus({ status: 'error', error: { name, message } })。An expected failure (returning { ok: false }) needs an explicit span.setStatus({ status: 'error', error: { name, message } }).

要点Key points

• 显式状态优先于自动状态：先 setStatus({ status: 'ok' }) 再抛错，span 仍是 ok。Explicit status beats the automatic one: setStatus({ status: 'ok' }) and then throw, and the span stays ok.
• 父 span 已结束时再开子 span，或创建记录本身失败，都会走 NOOP_TELEMETRY_CONTEXT：业务回调照常执行，只是不记录。Starting a child under a settled parent, or a failure while creating the record, goes through NOOP_TELEMETRY_CONTEXT: the business callback still runs, it just isn't recorded.
• 错误详情的读取是被动的：读 error.name 抛错时，状态退回为不带详情的 error。Reading error details is passive: if reading error.name throws, the status falls back to error without details.

工作原理How it works

1. startInMemorySpan()：检查父 span → createSpan() → callback(span) → Promise.resolve(result).then(settle ok, settle error)。startInMemorySpan(): check the parent → createSpan() → callback(span) → Promise.resolve(result).then(settle ok, settle error).
2. 同步抛错：先 settleSpan(…, true, error)，再 return Promise.reject(error)。A synchronous throw: settleSpan(…, true, error) first, then return Promise.reject(error).
3. 每个记录方法开头都是 if (recordedSpan.settled) return;，主体包在 try { … } catch {} 里。Every recording method starts with if (recordedSpan.settled) return; and wraps its body in try { … } catch {}.

要点Key points

• 用例是普通对象 { group, name, run() }，可以注册进 vitest、node:test 或任何框架；pi 自己的测试把它们挂到 InMemoryTelemetryContext 上。Cases are plain { group, name, run() } objects you can register with vitest, node:test or any runner; pi's own tests run them against InMemoryTelemetryContext.
• 被动性用 Proxy 检验：读取、枚举、取原型时都抛错的载荷不能让适配器抛错，也不能留下半条记录。Passivity is tested with a Proxy that throws on read, enumeration and prototype access: the adapter must not throw and must not keep half a record.
• fixture 的 getSpans() 返回规范化的 RecordedTelemetrySpan[]，可以先 flush 异步导出器。A fixture's getSpans() returns normalized RecordedTelemetrySpan[] and may flush an async exporter first.

工作原理How it works

1. createTelemetryAdapterConformance(async () => ({ context, getSpans, [Symbol.asyncDispose] }))。createTelemetryAdapterConformance(async () => ({ context, getSpans, [Symbol.asyncDispose] })).
2. for (const group of new Set(cases.map(c => c.group))) describe(group, () => …it(c.name, () => c.run()))。for (const group of new Set(cases.map(c => c.group))) describe(group, () => …it(c.name, () => c.run())).
3. 每个用例 await using fixture = await factory()：一个用例一个全新的适配器，结束时自动释放。Each case does await using fixture = await factory(): a fresh adapter per case, disposed automatically.

要点Key points

• 一致性用例里，second-child 同步返回、先结束（endSequence 1），first-child 等闸门打开才结束（2），parent 最后（3）。In the conformance case, second-child returns synchronously and ends first (endSequence 1), first-child ends once its gate opens (2), and parent last (3).
• 回调运行中调用 getSpans()：看到 settled: false 且没有 endSequence。Calling getSpans() while a callback runs shows settled: false and no endSequence.
• 存储无上限且只在本进程内：用于测试与本地诊断，每个测试 new 一个实例。Storage is unbounded and process-local: it is meant for tests and local diagnostics, one fresh instance per test.

工作原理How it works

1. createSpan()：id: state.nextSpanId++、parentId: parent?.id ?? null、复制开始属性（丢弃 undefined）。createSpan(): id: state.nextSpanId++, parentId: parent?.id ?? null, copied start attributes (dropping undefined).
2. mergeAttributes() 先复制再合并；中途抛错时整个调用被忽略，原属性不变。mergeAttributes() copies, then merges; if it throws midway the whole call is ignored and the attributes stay unchanged.
3. getSpans() 只在结束过的 span 上加 endSequence 字段。getSpans() adds the endSequence field only to settled spans.