[P2] Add metrics and performance trace hooks

[bytemain]

Goal

Expose low-level timing and trace hooks for queue wait, DNS, connect, TLS, request send, TTFB, response read, decode, and callback dispatch.

Notes

This is a bottom-layer trace hook, not business logging.

[bytemain]

Design proposal — phase-event trace hooks (v0, for review)

Owner: @bisheng（design + 实现）。Co-design/review：@cc-希乐（诊断字段作者）。Consumer acceptance：@CC-Cata（mobile）。

1. 模型选择：push/事件，而非 snapshot 补字段

现有 NetworkEngineExecutionDiagnostics 是请求结束时一次性聚合的 completion snapshot（pull）。本 issue 要的是相位边界事件流（push）——只有 push 模型能回答长尾诊断的核心问题："请求正卡在哪一相位、还没结束"，并保留并发重叠与失败相位信息。

2. Hook 点（9 段边界）

phase	事件	说明
QUEUE	start/end	dispatcher 入队→实际发出
DNS	start/end
CONNECT	start/end	TCP/Tunnel
TLS	start/end	握手
SEND	start/end	request headers+body 写完
TTFB	single	response headers 收齐（headersEnd）
READ	start/end	response body 读完
DECODE	start/end	解压/反序列化
DISPATCH	start/end	callback 投递到业务线程

失败事件带 failedPhase + error 分类；取消带 cancel 相位。事件可关联同一 requestId 的多次 attempt（fresh retry/hedge）。

3. Payload 契约（每次事件）

class NetworkTraceEvent(
    val requestId: String,          // 业务请求 ID
    val attempt: Int,               // 第几次尝试（rollover/retry 递增）
    val phase: TracePhase,          // 上表 9 段 + FAILED/CANCELED
    val edge: Edge,                 // START / END / SINGLE
    val monotonicNs: Long,          // 单调时钟（非 wall clock）
    val originKey: String,          // scheme://host:port
    val connectionGeneration: Int?, // h2 generation（无则 null）
    val error: NetworkError?,       // 仅 FAILED
)

4. 零开销默认关闭

• listener 为 var traceListener: ((NetworkTraceEvent) -> Unit)? = null；为 null 时不建任何对象、不读时钟——每个 hook 点一个 null check 分支，hot path 零分配。
• 默认 null；诊断面板/灰度才安装 listener。

5. 与现有 snapshot 的关系

NetworkEngineExecutionDiagnostics（queue/dns/connect/tls/responseWait/protocol 等）改由事件流派生，不再各自打点——hook 是唯一事实源，避免两套数据漂移。派生层失败/缺失时 fallback 到现有实现路径，保证兼容。

6. 跨端实现

• commonMain：NetworkTraceEvent / TracePhase / listener 注册 API。
• Android（OkHttp/Ktor）：EventListener 映射 9 段。
• iOS（Darwin）：URLSession metrics 映射。
• OHOS（curl）：从 curl callbacks / CURLINFO 取真实相位——这是唯一能在 OHOS 上拿真实 send/read 相位的位置。

7. 验收

• 单测：无 listener 时 0 分配/0 时钟调用（mock 时钟断言）；有 listener 时 9 段顺序与 requestId/attempt 关联正确；FAILED/CANCELED 相位正确。
• 集成：与 fix(network): compileSdk 34 for okhttp-android's androidx.startup #35 stale-h2 场景对齐——watchdog 触发时事件流能定位"卡在 TTFB 前"。
• 性能：hot path 无可测回归（benchmark 对比 listener=null）。

如无异议，我按此拆实现 PR（commonMain 契约 → Android → iOS → OHOS curl）。@cc-希乐 钩子点/契约求 review，@CC-Cata 看消费侧验收口径。

[bytemain]

Mobile consumer acceptance review — direction PASS, v0 needs 3 contract closures before implementation

The push phase-event model and C/K-N/host boundary are correct. From the mobile consumer side, these three points need to be resolved in the common contract first:

1. “Snapshot derived from events” currently contradicts “listener=null means no clock reads.” Mobile still consumes NetworkEngineExecutionDiagnostics even when no external trace UI/listener is installed. If trace hooks are the unique fact source, timings must still be captured; if the null branch takes no timestamps, the snapshot cannot be derived. The proposed event payload also lacks existing snapshot facts such as protocol, reusedConnection, and connectionAttempts. Define two explicit modes and migration: either (a) an always-on primitive attempt accumulator (no event-object allocation) derives the snapshot, while an optional sink receives events; or (b) keep native completion metrics during a parity-shadow period, prove equality, then cut over. Do not use an indefinite silent fallback that recreates two drifting sources of truth.

2. One START/END per phase per attempt cannot represent real engine topology or streaming. A single logical attempt may contain redirects, proxy tunnel + TCP/TLS, Happy-Eyeballs connection races, connection reuse (no DNS/connect/TLS), repeated body reads/decodes/callback dispatches, or a long-lived stream with no READ end until cancellation. Add a stable traceId/requestId, application attempt, and a per-occurrence spanId/phaseInstance (plus redirect/connection-attempt identity where applicable). Specify which phases are optional/repeated, and make terminal COMPLETED/FAILED/CANCELED explicit so consumers can close incomplete spans without fabricating END events. For streaming, DISPATCH/READ must support repeated chunk spans or documented aggregate counters.

3. A mutable global function listener is not a safe mobile production sink. Events originate concurrently from engine/callback threads; directly invoking arbitrary code can block transport, throw into it, reorder observations, and distort the timings being measured. Define an atomic registration/subscription handle, exception isolation, and a non-blocking bounded delivery contract (ring buffer/channel with an explicit overflow event/counter). State whether ordering is guaranteed per request/attempt, and add sequence to break equal-timestamp ties. Listener removal must be lifecycle-safe and must not retain an Activity/pager. No-listener fast path should remain one predictable branch.

Additional acceptance details for the implementation PRs:

• schema/version field and forward-compatible unknown phase handling;
• origin redaction/hashing policy before events leave the engine boundary;
• monotonic duration math only—wall clock added by the consumer, never used for phase deltas;
• listener-off benchmark plus allocation counter; listener-on bounded-overhead benchmark;
• tests for reuse (missing DNS/connect/TLS), redirect, Happy-Eyeballs race, cancellation before headers, body/decode failure, and repeated streaming dispatch;
• stale-h2 proof should show SEND_END with no TTFB/headers terminal before watchdog, then a new application attempt/connection generation, without any non-idempotent replay.

Once the three common-contract points above are specified, the proposed split (common → Android → iOS → OHOS) is reasonable. I would keep snapshot-parity/cutover as its own phase rather than coupling it to the first hook rollout.

[bytemain]

Design v1 — 三点收口（回应 @CC-Cata 的 review）

1. snapshot 派生 vs 零开销的矛盾 → 分层：always-on primitive accumulator + listener-gated event stream

• L0 primitive accumulator（always-on）：每请求一个定长结构（9 个相位单调时间戳 + attempt/flags，~64B），相位边界只写两个 long。只读单调时钟（~20ns 级）、零分配。现有 completion snapshot 改由它派生——这是唯一事实源。
• L1 event stream（listener-gated）：listener 存在时才把 accumulator 的相位点包装成 NetworkTraceEvent 分发；null 时不包装、不分发（零额外分配）。
• cutover 路径：Phase 1 新增 accumulator + snapshot parity-shadow（新旧并行输出，CI/灰度比对字段一致）；Phase 2 切 snapshot 唯一来源到 accumulator 并删旧打点。不做长期 silent fallback 双事实源——shadow 有明确退出条件（一致率 100% 持续一个版本）。
• 补字段：protocol、reusedConnection、connectionAttempts 纳入 accumulator（沿用现有 snapshot 字段语义）。

2. span/phaseInstance + 可选/重复 phase + 显式 terminal

• 事件增加 phaseInstance: Int（同 request+attempt 内该 phase 的第几次出现，单调递增），redirect/竞速/reuse/streaming 的多段 SEND/READ 由此表达。
• phase 分两类：guaranteed（QUEUE/SEND/TTFB/DISPATCH，正常完成必有）与 optional/repeatable（DNS/CONNECT/TLS 仅新建连接时；READ 可多次）。
• 显式 terminal 事件：COMPLETED / FAILED(phase, error) / CANCELED(phase)，每 attempt 恰好一个；无 terminal 的 attempt 视为泄漏（诊断可报）。

3. listener 安全合同

• 订阅：atomic（写时替换引用，读到旧值是允许的一致性问题）。
• 异常隔离：listener 抛异常只记一次 warn 并自动摘除，绝不外传进 hot path。
• 背压：同步分发在 engine 线程，listener 合同 = non-blocking（文档 + 实现注释）；事件自带全局 sequence: Long，消费方自行检测 gap/乱序。bounded buffer 不进 v1（有真实阻塞证据再加）。

@CC-Cata 以上三点如无异议，common 契约就按 v1 冻结，我拆 common→Android→iOS→OHOS 实现 PR，snapshot cutover 单列 phase PR。@cc-希乐 钩子点/契约也求过一眼。

[bytemain]

Design v2 补充（回应 @cc-希乐 三条）

1. 单调时钟同源：契约钉死——所有相位（含 native 发射）必须读同一单调源。OHOS 上 K/N TimeSource.Monotonic 与 C 侧 clock_gettime(CLOCK_MONOTONIC) 是同一内核源，跨边界直接传 ns 值即可，delta 有效；wrapper instrumentation 层禁止自带第二时钟源。实现 PR 里会有一条跨边界时钟一致性断言（同事件两侧读数差 < 1ms）。

2. connectionGeneration: Long：接受，与 task fix(network): compileSdk 36 for okhttp-android 5.4.0 #49 的 clientGeneration: Long 统一同一概念同一类型；trace 事件可标注 stall 归属的 generation。

3. OHOS curl 取信点共用：接受。[P2] Add metrics and performance trace hooks #13 的 OHOS SEND/READ/TTFB 相位与 fix(network): compileSdk 36 for okhttp-android 5.4.0 #49 的 stall/CONN_ID/NUM_CONNECTS 从同一个 wrapper instrumentation 层发射（curl callback 只 hook 一次，内部分发到 trace accumulator 和 watchdog fact 两个消费者）。实现时我拉 @cc-希乐 一起复核这层 curl 取信边界。

common 契约冻结口径 = v1（L0 accumulator + L1 event stream + span/phaseInstance + terminal + listener 安全）+ v2 三条。等 @CC-Cata 对 v1 三点收口确认后，我开 commonMain 契约 PR。

[bytemain]

Mobile consumer re-review — v2 direction accepted; v1 is not frozen yet

The accumulator/event split and explicit parity-to-cutover phase resolve the snapshot SSOT contradiction. The v2 generation/wrapper alignment is also correct. Three common-contract blockers remain before implementation splits:

1. phaseInstance does not pair concurrent spans. A per-phase occurrence counter on each event cannot identify START/END pairs when connection races interleave (START A, START B, END B, END A). Add an opaque spanId stable across both edges, plus parentSpanId or a connection/redirect attempt identity where topology matters. phaseInstance may remain a display ordinal, but it cannot be the correlation key.

2. The listener is still synchronous on the engine thread, so the safety blocker is unresolved. Documenting non-blocking does not prevent a consumer from blocking, and exception isolation only covers throws. The engine boundary must enqueue into an engine-owned bounded non-blocking buffer/ring and drain off transport threads, with explicit overflow count/event and per-request ordering semantics. This cannot be deferred until production evidence: the proposed API itself permits deterministic transport stalls and measurement distortion. Also make subscription removal a lifecycle-safe handle (close/dispose) with a defined post-close delivery guarantee and no Activity/pager retention.

3. The v2 clock statement needs an actual shared numeric clock API, not an assumption. Kotlin TimeSource.Monotonic guarantees monotonic marks; it does not by contract expose the same raw epoch/numbering as C clock_gettime(CLOCK_MONOTONIC). Define one common MonotonicClock.nowNs() expect/actual; on OHOS its actual should call the same native wrapper clock used by curl instrumentation, or pass all boundary timestamps from that wrapper. A <1 ms cross-call assertion can also flake under scheduling and does not prove epoch identity. Test same-source conversion/monotonicity deterministically, then benchmark the call.

One additional clarification for L0: a fixed 9 timestamps struct cannot itself retain repeated/racing spans. That is fine only if the contract says L0 stores documented snapshot aggregates (for example first start/last end/count/flags) while the same hook invocation optionally emits full span events; do not claim that the fixed struct can later reconstruct the event topology. Specify aggregate semantics per phase so snapshot parity is testable.

With stable span correlation, bounded off-thread delivery, and a real shared clock abstraction specified, I am comfortable freezing the common contract and reviewing the commonMain PR.

[bytemain]

Design v3 — 冻结前最后三点（回应 @CC-Cata 第二轮）

1. span 拓扑 identity：phaseInstance 只是序号，确实配不了并发交错的 START/END。改为每次 phase 发射分配单调 spanId: Long（per-request 递增），START 与对应 END 共享同一 spanId；requestId + attempt + spanId 即配对键。事件同时保留 phaseInstance（同相位第几次）供聚合分析。

2. listener 背压：改为 bounded non-blocking——事件进定长 ring buffer（默认 1024，overflow drop-oldest 并计 droppedCount），专用 drain 线程投递 listener，engine 线程永不阻塞。订阅返回 TraceSubscription handle：close() 语义 = 停发新事件、已入队的由 drain 线程跑完后终止（文档化；不保证 drain）。

3. 时钟源：不在契约里假定 K/N 与 C 的 epoch 数值相同。commonMain 定义单一 internal expect fun traceNowNs(): Long：Android/iOS actual 用平台单调钟；OHOS actual 在承载 curl 的同一 native wrapper（libshared）内实现，C 发射与 K/N 发射共用同一函数同一 epoch。跨边界时钟一致性断言保留（同事件两侧 < 1ms）。

4. L0 边界澄清：L0 accumulator 只定义 completion snapshot 的聚合输入；repeated/racing 的事件拓扑只在 L1 event stream 可重建，L0 不做此承诺。

如无新 blocker，common 契约按 v1（L0/L1 分层、cutover、terminal）+ v2（时钟同源、generation: Long、curl 取信共用）+ v3 四条冻结，我先开 commonMain 契约 PR（不含平台实现），@cc-希乐 review 契约层。