剖析与遥测

本页中的所有地址和偏移均适用于 libtpu-0.0.40-cp314 wheel 中的 libtpu.so（build-id 89edbbe81c5b328a958fe628a9f2207d）。其他版本会有所不同。

摘要

libtpu 携带了一份完整的 TensorFlow/XLA profiling 栈副本，即 JAX、PyTorch-XLA 和 TensorBoard 已经使用的同一套 XSpace/XPlane/XLine/XEvent/XStat 模型，外加一个 TPU 专用的设备 trace 编解码器，以及一套与之正交的核心状态遥测 schema。一份 profile 会先在设备端以定宽硬件 trace packet 流的形式被捕获，再被编码成压缩的 riegeli blob，按芯片家族解码成 proto2 TraceEntry 消息，最后被塑形为一个 XSpace 的 device XPlanes，并通过 PJRT Profiler 扩展以序列化 blob 形式离开库。本节从二进制中重建该流水线的每个阶段；本页是总览地图。

整个子系统刻意拆成两个互不交叉的格式。xprof（时间序列事件 trace）回答 “这个时间区间里发生了什么？”，其根是 XSpace，由 host 和 device 子 profiler 组成的 tsl::profiler::ProfilerCollection 产生，并通过 PJRT C-ABI 拉取。tpu_telemetry（某一时刻的状态快照）回答 “每个核心此刻正在做什么？”，其根是 AllCoreStateSummaries，由主机端 xdb（TPU debugger）状态服务器产生，并由 Cloud TPU monitoring 和 Megascale hang-detector 通过 gRPC 拉取。两者在线路层从不相交：PLUGIN_Profiler_CollectData 只提供 XSpace，两个 state-summary RPC 从不发出 XSpace。它们只通过 TpuProfilerControlListener 相遇；该 listener 注册编译器/调试元数据，profiler 用它给 XEvent 标注源位置，xdb 服务器用它把 PC 解析到 HLO 位置。

本页负责说明 capture → encode → decode → xplane orientation、按 DeviceType 的 profiler 分发，以及 trace-point / payload 分类，也就是流水线形状和到 21 个同级页面的索引。这里不重新推导各自内部细节：PJRT 扩展结构体和生命周期见 PJRT Profiler 扩展（已写）；bit 级 wire format、各家族 payload 字段映射、metadata-id 目录和 telemetry schema 都各有自己的深入页面，下面会链接且不在此重复。

作为定位，本节重建的契约是：

两种格式，一个边界： xprof XSpace（事件 trace，PJRT C-ABI）对 tpu_telemetry AllCoreStateSummaries（状态快照，gRPC），以及二者唯一共享依赖 TpuProfilerControlListener。
五阶段 xprof 流水线： 设备端定长 16 字节 trace packets → riegeli+zlib transport → 按家族的 TraceCodecInterface::DecodeEntry → proto2 TraceEntry → TpuXLineBuilder::AddEvent 进入一个 XSpace 的 device XPlanes。
四层 xprof 数据模型： XSpace ⊃ XPlane ⊃ XLine ⊃ XEvent ⊃ XStat，带 interned XEventMetadata/XStatMetadata，与上游 TF 相同，并由 TPU event/stat ids 扩展。
按 DeviceType 的 codec 分发： xprof::tpu::GetTraceCodec(asic_sw::DeviceIdentifiers, int) 选择芯片家族 codec（pxc/vfc/vlc/glc/gfc 定宽；jxc legacy PerformanceTraceEntry），每个 codec 都有自己的 trace-point band 布局。


Trace 模型	`tensorflow.profiler.XSpace` ⊃ `XPlane` ⊃ `XLine` ⊃ `XEvent` ⊃ `XStat`（4 层事件树，interned metadata）
捕获格式	固定 16 字节（128-bit）LSB-first 硬件 trace packet，按芯片家族变化
Transport	`riegeli::ZlibReader<riegeli::StringReader>`（由 packet 组成的 zlib-inflated blob）
设备解码	`xprof::tpu::DecodeTraceBuffers<TraceEntry>` @ `0xf59ffa0` (pxc) — 遍历 packets → `TraceEntry`
Codec 选择器	`xprof::tpu::GetTraceCodec(asic_sw::DeviceIdentifiers, int)` @ `0xf5a2900`
设备子 profiler	`xprof::tpu::TpuProfilerImpl::CollectData(XSpace*)` @ `0xef34860`
后端	`tsl::profiler::ProfilerCollection`（由 `CreateProfilers` @ `0x1cf50860` 构建）
xprof 导出	通过 PJRT Profiler 扩展（type 1）+ legacy `TpuProfiler_*` C-ABI 输出序列化的 `XSpace` bytes
Telemetry schema	`platforms/deepsea/jellyfish/xdb/tpu_telemetry/tpu_telemetry.proto`（6 msgs，2 enums）→ `AllCoreStateSummaries`，通过 gRPC 拉取
运行门控	`xprof::tpu::TpuProfilerControlListener` @ `GetOrCreateTpuProfilerControlListener` `0xf332800`

Capture → Encode → Decode → XPlane 流水线

子系统的 xprof 半边是从硬件 ring buffer 到序列化 XSpace 的五阶段流程。每个阶段由不同的同级页面负责；本节只命名这些阶段、各边界处的符号，以及阶段间的交接。

text

[1] HW trace ring buffer (per core, per sequencer)
      │  emits fixed 16-byte packets, LSB-first:
      │  [valid:1][started:1][trace_point_id:8][block_id:3|6][timestamp:48|45][payload @ bit 61 …]
      ▼
[2] riegeli ZlibReader<StringReader> inflate          (DecodeTraceBuffers @ 0xf59ffa0)
      │  one compressed blob → decompressed stream of packets
      ▼
[3] TraceCodecInterface::DecodeEntry  (per chip family; pxc DecodeEntry @ 0xf5af3a0)
      │  GetBits(1)valid · GetBits(1)started · GetBits(8)id → 111-entry jump table @ 0xab85bc0
      │  per-event Decode<Name>(): header + [TraceIdHeader 21/3/12] + typed payload; total-bit CHECK
      ▼
[4] proto2 TraceEntry  (oneof variant = the event; oneof tag @ +0x28)
      │
      ▼
[5] xprof::tpu TpuXLineBuilder::AddEvent → device-plane XEvent + XStats
      │  trace_point_id → XEventMetadata.name ; timestamp → XEvent offset/duration_ps ; scalars → XStat
      ▼
   one tensorflow.profiler.XSpace  ── serialized ──▶ PLUGIN_Profiler_CollectData buffer
```text

### [1] 捕获 — 设备端 trace points

每个 TPU core 的硬件会把 trace events 作为定长 16 字节 packets 写入 per-core ring buffers，采用 LSB-first。packet 以 2-bit framing 前缀（`valid`、`started`）、8-bit `trace_point_id`、3 或 6-bit `trace_point_block_id`，以及 48 或 45-bit cycle-counter `timestamp` 开头；这是 61-bit framing+header envelope 中固定的 59-bit header，之后每个事件的定宽 payload 从 bit 61 开始。`valid` bit 是 empty-slot sentinel，使 buffer 可在没有 count 的情况下 drain；`started` 用来捕获被撕裂的硬件写入。bit 级布局、framing 语义以及 decode/encode 双分发见 [TraceEntriesCoder](trace-entries-coder.md)；各 band 的 payload 字段映射拆分到下面四个 payload 页面。

### [2] 编码 / Transport — riegeli + zlib

打包后的 packets 从不以 raw 形式存储：设备 trace blob 会被包进 `riegeli::StringReader`，通过 `riegeli::ZlibReader` inflate，一次性读完整体，再按每 16 字节一个 packet 遍历。这是 [riegeli Trace Container](riegeli-trace-container.md) 负责的 container 层。生产侧也用同一套 `riegeli`/`PutBits` primitive 编码 packets（decode 的 byte-exact inverse）。

### [3] 解码 — 按家族的 codec

`DecodeTraceBuffers<TraceEntry>` 遍历解压后的 stream，并对每个 packet 调用 codec 的虚函数 `DecodeEntry`。`DecodeEntry` 先窥看 2 个 framing bits 和 8-bit `trace_point_id`，通过 111-entry `rel32` jump table（pxc @ `0xab85bc0`）分发到 anonymous-namespace `Decode<Name>()`，后者重新解码 header、可选的 36-bit `TraceIdHeader` 和 typed payload，然后用硬编码 `CHECK` 常量校验总消耗 bit 数。decoder 机制由 [TraceEntriesCoder](trace-entries-coder.md) 负责；得到的 proto2 `TraceEntry`（oneof tag at `+0x28`）是解码产物。

### [4] TraceEntry — 解码后的 proto

`TraceEntry` 是一个 proto2 消息，active oneof variant 标识事件。wire `trace_point_id`（分 band、有空洞）*不是* proto oneof field number（稠密）：decode 以 wire id 索引 jump table，encode 按 oneof field 分发。这组双 id 空间配对及主 id↔field registry 由 [TracePoints Master Registry](tracepoints-master-registry.md) 负责。

### [5] XPlane 塑形 — TraceEntry 到 XEvent

`xprof::tpu` 把每个 `TraceEntry` 转成 device-plane `XEvent`：`TraceHeader.trace_point_id` 变成 per-plane `XEventMetadata.name`（enum string），`TraceHeader.timestamp`（cycle counter）变成 `XEvent` `offset_ps`/`duration_ps`，解码出的 variant scalars 变成 `XStat`。具体哪些内容进入 `XEventMetadata.metadata`、scalars 如何映射到 stats，由 [TraceEntry → XEvent/XStat](trace-entry-to-xevent.md) 负责。Host events 走另一条路径（见下），并折入同一个 `XSpace`。

> **NOTE —** cycle-counter `timestamp`（48 或 45 bits）是*原始设备时钟*，不是 picoseconds。cycle→ps 转换因子（按 gen 的设备时钟频率）和 per-line `timestamp_ns` origin 是在下游 `TpuXLineBuilder` 中应用的，而不是在 codec 中。把 on-wire timestamp 当作 picoseconds 的重实现会差一个 clock period，并错误计算 wrap interval。见 [TraceEntriesCoder](trace-entries-coder.md)。

---

## xprof 数据模型

解码后的事件落入规范 TensorFlow profiling tree；该 tree 在 TF/JAX/PyTorch-XLA 间相同，因此 TPU profile 可以在 stock TensorBoard 中打开。libtpu 带有自己的 `tsl::profiler` builders 副本（`XPlaneBuilder` @ `0x1cf4d9a0` 用于 `GetOrCreateLine`，`XLineBuilder::AddEvent` @ `0x1cf4dc40`），确认该模型不是仅被导入，而是在二进制中实例化。

| 层级 | 角色 | 关键字段 | 归属 |
|---|---|---|---|
| `XSpace` | 一次 profiling session 的根容器 | `XPlane` 列表 | 本页（opaque blob） |
| `XPlane` | 一个设备 core 或一个 host thread-group | `id`, `name` (`/host:0`, `/device:TPU:0`, …), `XLine[]`, interned `XEventMetadata[]` + `XStatMetadata[]` | [XPlane / XStat / TraceMe](xplane-xstat-traceme.md) |
| `XLine` | plane 内的一条 timeline（一个 core/stream） | `id`, `name`, `timestamp_ns` origin, `duration_ns`, `XEvent[]` | [XPlane / XStat / TraceMe](xplane-xstat-traceme.md) |
| `XEvent` | 一个 point 或 duration event | `metadata_id` (FK → `XEventMetadata`), `offset_ps`, `duration_ps`, `XStat[]` | [XEvent Metadata IDs](xevent-metadata-ids.md) |
| `XStat` | event 上的 key/value annotation | `metadata_id` (FK → `XStatMetadata`), variant value (`int64`/`uint64`/`double`/`bytes`/str-ref) | [XStat Metadata IDs](xstat-metadata-ids.md) |

每个 `XPlane` 的两份 metadata list 都是 *interned tables*：`XEvent` 只携带 `metadata_id` index，name/category 只在 `XEventMetadata` 中存一份；stats 同理。因此 metadata-id catalogs 需要单独成页：这些 ids 是每个 consumer 都必须与 producer 共享的字典。

### Host events 与 device events

两个来源共同填充一个 `XSpace`。**Host** events 来自 TPU-runtime threads 上的 `tsl::profiler::TraceMe` scopes（`TpuCompile`、`TpuExecute`、queue submission、megascale transport），并通过 `HostTracer`/`ThreadpoolProfilerInterface` 子 profilers 落在 `/host:0` plane。**Device** events 来自按上文 drain 并解码的 per-core 硬件 ring buffers，并通过 `TpuProfilerImpl` 落在 `/device:TPU:N` planes。`TraceMe` 宏机制和 host-plane 塑形由 [XPlane / XStat / TraceMe](xplane-xstat-traceme.md) 负责。

> **GOTCHA —** device-trace `trace_point_id` 空间（分 band 的硬件 enum，有空洞；pxc decode jump table at `0xab85bc0` 把 8-bit wire id 上界设为 `0x6e`=110 — `cmp $0x6e,%rax; ja <error>` @ `0xf5af451` — 其中 64 个 index 被处理，另有 `DummyTracePoint` variant）与 `XEventMetadata.metadata_id` 空间（稠密的 per-plane interning index）是*不同命名空间*。codec 的 id 会在第 5 阶段映射为 `XEventMetadata` name string；随后 `XEvent.metadata_id` 会在每个 plane 内重新分配。把两者混为一谈的重实现会错误地给每个 device event 建 key。见 [XEvent Metadata IDs](xevent-metadata-ids.md) 和 [TracePoints Master Registry](tracepoints-master-registry.md)。

---

## 后端：ProfilerCollection 与子 Profilers

xprof 导出路径由一个 `tsl::profiler::ProfilerCollection` 驱动，它是一个 `ProfilerInterface` 子 profilers 向量，由 `CreateProfilers` @ `0x1cf50860` 遍历全局 factory registry 组装；每个子 profiler 通过 `RegisterProfilerFactory` @ `0x1cf50780` 加入该 registry。`ProfilerCollection` 是 PJRT `PLUGIN_Profiler` handle 拥有并将 `Start`/`Stop`/`CollectData` 委托给的对象；该委托、C-ABI 生命周期和 handle 布局已完整记录在 [PJRT Profiler 扩展](../pjrt/ext-profiler.md)，本页不重复。

每个 backend op（`ProfilerCollection::Start` @ `0xf6a1640`、`Stop` @ `0xf6a16c0`、`CollectData(XSpace*)` @ `0xf6a1740`）都会遍历内部向量，并在每个子 profiler 上调用对应 slot。已确认成员：

| 子 profiler | 侧 | 关键符号 | 地址 |
|---|---|---|---|
| `xprof::tpu::TpuProfilerImpl` | device — drain per-chip ring buffers、解码、构建设备 planes | `TpuProfilerImpl::CollectData(XSpace*)` | `0xef34860` |
| `xla::profiler::HostTracer` | host — `TraceMe`/CPU events 进入 `/host:0`（factory 在 `xprof::cpu` 中） | `HostTracer::CollectData(XSpace*)` | `0xf32fb40` |
| `tsl::profiler::ThreadpoolProfilerInterface` | host — threadpool dispatch events | `ThreadpoolProfilerInterface::CollectData(XSpace*)` | `0xf3326c0` |

`CreateProfilers` 会把每个 factory output 包在 `ProfilerController` 中以做 crash isolation；完整 factory inventory 会在多个 static-init blocks 中惰性填充，尚未穷尽列举（完整性 LOW confidence — PJRT 页面也记录了同一缺口）。

### 运行门控

Device profiling 与 execution *并发*运行，由 `xprof::tpu::TpuProfilerControlListener` singleton（`GetOrCreateTpuProfilerControlListener` @ `0xf332800`）调停。每个 chip driver 在打开自己的 trace ring buffer 之前会查询 `CanStartProfiler(TpuChipLocation, TpuChipProfiler*, int)` @ `0xf3328c0`，并轮询 `MustStopProfiler(TpuChipLocation)` @ `0xf332a00` 以支持运行中停止。该 listener 也是共享的 PC→HLO metadata 来源，让 xdb state server 能填充 `SequencerInfo.hlo_location`；这是 trace 与 telemetry 两半唯一接触的地方。

---

## 按 DeviceType 的 Codec 分发

不存在单一的 device-trace codec：每个 TPU 芯片家族都有自己的 `TraceCodecInterface<TraceEntry>`（vtable slots `DecodeEntry`/`EncodeEntry`/`GetMaxEntrySize`/`GetEntryPacketSize`），运行时由 `xprof::tpu::GetTraceCodec(asic_sw::DeviceIdentifiers, int)` @ `0xf5a2900` 从按芯片 codename keyed 的 `util_registration::StaticMapBase` factory 中选择。packet size（16 bytes）和 61-bit framing+header envelope 是通用的；各家族不同的是 header 切分（3-vs-6-bit `block_id`、48-vs-45-bit timestamp）以及每个 trace-point 的 payload 字段映射。selector 和 producer/reader wiring 由 [Per-DeviceType Profiler Struct](per-devicetype-struct.md) 与 [kDeviceTypeInfo Producer / Readers](kdevicetypeinfo-producer-readers.md) 负责。

| 家族 | `CreateTraceCodec` | TraceEntry 类型 | block_id | timestamp | Codec 页面区域 |
|---|---|---|---|---|---|
| pxc | `plc::driver::profiler::CreateTraceCodec` @ `0xf5af2c0` (pxc family) | fixed-width `TraceEntry` | 3 | 48 | [TraceEntriesCoder](trace-entries-coder.md) |
| vfc | `vfc::driver::profiler::CreateTraceCodec` @ `0xf5f5da0` | fixed-width `TraceEntry` | 6 | 45 | [Payload: vfc/vlc/gfc](payload-vfc-vlc-gfc.md) |
| vlc | `vlc::driver::profiler::CreateTraceCodec` @ `0xf5d5180` | fixed-width `TraceEntry` | 3 | 48 | [Payload: vfc/vlc/gfc](payload-vfc-vlc-gfc.md) |
| glc | `glc::driver::profiler::CreateTraceCodec` @ `0xf6282e0` | fixed-width `TraceEntry` | 6 | 45 | [Payload: vfc/vlc/gfc](payload-vfc-vlc-gfc.md) |
| gfc | `gfc::driver::profiler::CreateTraceCodec` @ `0xf65ed00` | fixed-width `TraceEntry` | 6 | 45 | [Payload: vfc/vlc/gfc](payload-vfc-vlc-gfc.md) |
| jxc | (legacy path) | `jxc::PerformanceTraceEntry` | — | — | [Payload: jxc Legacy](payload-jxc-legacy.md) |

> **QUIRK —** jxc 使用*不同*的 TraceEntry 类型，即 `asic_sw::driver::deepsea::jxc::PerformanceTraceEntry`，由它自己的 `DecodeTraceBuffers<PerformanceTraceEntry>` 实例解码，而不是当前五个家族使用的共享 fixed-16-byte `TraceEntry` codec。假设所有 gens 共用一种 packet schema 的重实现会误解析 jxc traces。jxc DMA/HbmMux/brn_perf 细节见 [jxc DMA / HbmMux / brn_perf](jxc-dma-hbmmux-brnperf.md) 和 [Payload: jxc Legacy](payload-jxc-legacy.md)。

---

## Trace-Point / Payload 分类

各家族的 trace points（每个 gen 的基数不同，取决于 gen 有 78–128 个 oneof variants；pxc=99）并不是一个扁平 enum，而是组织成若干连续 `trace_point_id` range 的*子系统 bands*，band 之间有保留空洞，均分发到共同 error label。decode jump-table index span 宽于 variant count（pxc 把 wire id 限在 `0x6e`=110，vlc 在 `0x8f`=143，vfc 在 `0x5f`=95，gfc 在 `0x64`=100），因为带空洞的 bands 会把保留 slot 路由到 error label。这些 bands 按硬件单元切分 device-trace 空间；每个 band 的 payload 字段映射都在专页中，因此本 opener 保持为地图，而不是 dump。

| Band | `trace_point_id` range (pxc) | 子系统 | Payload 页面 |
|---|---|---|---|
| UHI | 0–10 | host-DMA / address translation | [Payload: UHI/OCI/ICI/DMA](payload-uhi-oci-ici-dma.md) |
| OCI | 20–27 | on-chip interconnect engine | [Payload: UHI/OCI/ICI/DMA](payload-uhi-oci-ici-dma.md) |
| ICI | 40–55 | inter-chip-interconnect / collective fabric | [Payload: UHI/OCI/ICI/DMA](payload-uhi-oci-ici-dma.md) |
| TCS | 80–97 | TensorCore sequencer sync/control + throttle | [Payload: SparseCore Band](payload-sc-band.md) |
| BC | 100–110 | BcFsm / Bcs / BcOci (SparseCore/broadcast) controllers — pxc top-level indices `BcFsmChannelController0..10` | [Payload: SparseCore Band](payload-sc-band.md) |
| CMQ | (sub-dispatch) | command-queue / VPU DMA — 在 BC case bodies *内部*到达，而不是独立 top-level wire id | [Payload: UHI/OCI/ICI/DMA](payload-uhi-oci-ici-dma.md) |
| (reserved) | 11–19, 28–39, 56–79, 98–99 | 未使用 — 全部 → common error label `0xf5b032f` | n/a (decode rejects) |
| (out of range) | ≥ 111 | 由 `cmp $0x6e,%rax; ja` bound @ `0xf5af451` 拒绝 | n/a |

少量横跨 bands 的 render/timeline 关注点位于 raw bands 之上：ICR DMA-timeline derivation（[ICR DMA-Timeline Band](icr-dma-timeline-band.md)）、DMA endpoint rendering（[DMA Endpoint Rendering](dma-endpoint-rendering.md)）以及 v7x performance-counter lines（[v7x Perf-Counters](v7x-perf-counters.md)）。多数 variant messages 还在 header 后立即携带共享 `TraceIdHeader`（`transaction_id:21`, `core_id:3`, `chip_id:12│14`）：pxc 上 36 bits，vfc/vlc/glc/gfc 上因 `chip_id` 扩至 14 而为 38 bits；这是 per-transaction identity，可把多 packet DMA 拼接回来；某些 events（OCI read/write）会携带三个。

> **GOTCHA —** band ranges 与 reserved gaps 是*按家族*变化的。上面的 pxc ranges 是 worked example；随着 trace-point 基数增长（约 99 → 约 144 events），vfc/vlc/glc/gfc 会移动 band boundaries。band detection 应由按家族的 decode jump table 驱动，绝不要用硬编码 pxc range。见 [TracePoints Master Registry](tracepoints-master-registry.md)。

---

## Telemetry：正交的状态快照

`tpu_telemetry.proto`（package `platforms_deepsea.jellyfish.xdb.tpu_telemetry`，6 messages，2 enums，无 imports）**不是** xprof 流水线的一部分，而是一个独立的、按需拉取的 core-state snapshot，由主机端 xdb state server 产生；二进制中的 `platforms_deepsea::jellyfish::xdb::tpu_telemetry::*` proto symbols（如 `AllCoreStateSummaries`、`CurrentCoreStateSummary`、`SequencerInfo`、`QueuedProgramInfo`、`TpuCoreIdentifier`、`TpuCoreOnChipProto`）和 descriptor path `platforms/deepsea/jellyfish/xdb/tpu_telemetry/tpu_telemetry.proto` 证实了这一点。其根 `AllCoreStateSummaries` 是一个 `map<int32 global_core_id, CurrentCoreStateSummary>`；每个 `CurrentCoreStateSummary` 携带 `repeated SequencerInfo`（每个硬件 sequencer：`pc`、`tag`、`tracemark`、`program_id`、`run_id`、`hlo_location`）和一个 `repeated QueuedProgramInfo` launch queue。完整的逐字段 schema、producer/consumer graph（xdb debugger、Cloud TPU `RuntimeMetricService.GetTpuRuntimeStatus`、Megascale hang-detector），以及与 companion hardware-telemetry protos 的边界，由 [tpu_telemetry.proto](tpu-telemetry-proto.md) 负责。

它只携带*核心执行状态*，不包括 HBM bytes、temperature、watts、ICI BER 或 ECC counters；这些在该 schema 之外的专用 companion protos（`utilization_metrics.proto`、`power_metrics.proto`、`error_report.proto` 等）中。唯一感知 gen 的表面是 `TpuCoreTypeProto` / `TpuSequencerTypeProto` enum，它编码了 SparseCore 的演进：`SPARSE_CORE_V0`（sequencer + address handler）对当前 `SPARSE_CORE`（scalar sequencer + Tile-Access-Core + Tile-Execute-Core sequencers，ids 4/5/6）。

> **NOTE —** telemetry 和 xprof 由不同 runtime 子系统产生（xdb state server 对 `tsl::profiler` `ProfilerCollection`），并通过不同 channel 消费（gRPC pull 对 PJRT C-ABI）。它们只共享很小的*语义*重叠（都引用 `run_id`/`launch_id` 和 HLO location）以及一个*实现*依赖（`TpuProfilerControlListener` 的 PC→HLO metadata）。它们从不被序列化进同一个 blob。

---

## 章节地图

21 个同级页面划分如下。本页是导览；每个链接都是负责其内部细节的深入页面。

### 入口与 ABI

- [PJRT Profiler 扩展](pjrt-profiler-extension.md) — 作为 profiling-section 视图的 type-1 extension
- [TpuProfiler ABI](tpu-profiler-abi.md) — 共享同一 backend 的 legacy `TpuProfiler_*` C-ABI 五元组
- [Per-DeviceType Profiler Struct](per-devicetype-struct.md) — codec selector 和 per-family profiler struct
- [kDeviceTypeInfo Producer / Readers](kdevicetypeinfo-producer-readers.md) — 谁填充并读取 device-type table

### 捕获与 transport（wire）

- [TraceEntriesCoder](trace-entries-coder.md) — fixed-16-byte packet、framing、header、decode/encode dispatch
- [riegeli Trace Container](riegeli-trace-container.md) — zlib/`riegeli` compressed transport
- [TracePoints Master Registry](tracepoints-master-registry.md) — wire-id ↔ oneof-field 双 id 空间主表

### Payload 字段映射（按 band/family）

- [Payload: UHI/OCI/ICI/DMA](payload-uhi-oci-ici-dma.md) — host-DMA、on-chip interconnect、fabric bands
- [Payload: SparseCore Band](payload-sc-band.md) — TensorCore/SparseCore sequencer band
- [Payload: vfc/vlc/gfc](payload-vfc-vlc-gfc.md) — newer-family payload deltas
- [Payload: jxc Legacy](payload-jxc-legacy.md) — legacy `PerformanceTraceEntry` schema
- [ICR DMA-Timeline Band](icr-dma-timeline-band.md) — DMA timeline derivation
- [DMA Endpoint Rendering](dma-endpoint-rendering.md) — endpoint-pair rendering
- [jxc DMA / HbmMux / brn_perf](jxc-dma-hbmmux-brnperf.md) — jxc DMA / HBM-mux / perf-counter 细节
- [v7x Perf-Counters](v7x-perf-counters.md) — v7x performance-counter lines

### 塑形成 XSpace

- [TraceEntry → XEvent/XStat](trace-entry-to-xevent.md) — decode-product → XPlane translation
- [XPlane / XStat / TraceMe](xplane-xstat-traceme.md) — xprof builders 和 host `TraceMe` emission
- [XEvent Metadata IDs](xevent-metadata-ids.md) — interned event-id dictionary
- [XStat Metadata IDs](xstat-metadata-ids.md) — interned stat-id dictionary

### Telemetry（正交）

- [tpu_telemetry.proto](tpu-telemetry-proto.md) — core-state snapshot schema 及其 RPC graph
- [Task Proto](task-proto.md) — 周边 task/session descriptor

---

## 交叉引用

- [PJRT Profiler 扩展 (type 1)](../pjrt/ext-profiler.md) — C-ABI 入口点：extension node、`PLUGIN_Profiler_Api` vtable、`Create/Start/Stop/CollectData/Destroy` 生命周期，以及本页所依赖的 `ProfilerCollection` bridge
- [TraceEntriesCoder](trace-entries-coder.md) — 本页在阶段 1–4 中概述的 bit-level capture/encode/decode wire format
- [TraceEntry → XEvent/XStat](trace-entry-to-xevent.md) — 阶段 5，即 decode-product 到 XPlane 的 translation
- [XPlane / XStat / TraceMe](xplane-xstat-traceme.md) — xprof builders 以及与 device path 汇入同一个 `XSpace` 的 host-event path
- [tpu_telemetry.proto](tpu-telemetry-proto.md) — 正交的 state-snapshot format 以及与 xprof 的边界
- [TracePoints Master Registry](tracepoints-master-registry.md) — 本页所映射的 trace-point id space 与 band taxonomy

剖析与遥测 ​

摘要 ​

Capture → Encode → Decode → XPlane 流水线 ​

剖析与遥测

摘要

Capture → Encode → Decode → XPlane 流水线