Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

调试与可观测性指南

本指南介绍如何调试、录制、回放和监控 adora 数据流。面向希望了解数据流故障原因、测量性能或离线复现问题的新用户。

目录

前提条件

在使用主题检查命令（topic echo、topic hz、topic info）之前，通过以下任一方式启用调试消息发布：

方式 1：CLI 标志（推荐）

adora start dataflow.yml --debug
adora run dataflow.yml --debug

方式 2：YAML 描述符

_unstable_debug:
  publish_all_messages_to_zenoh: true

这会告诉守护进程将所有节点间消息发布到 Zenoh，协调器可以通过 WebSocket 将其代理给 CLI 客户端。没有此标志，主题检查命令将返回错误。

The record, replay, logs, list, top, graph, node info/restart/stop, param, and doctor commands do not require this flag. The topic pub command does require it.

快速调试清单

当出现问题时，按以下顺序排查：

# 1. Run full environment diagnosis
adora doctor --dataflow dataflow.yml

# 2. What dataflows are active?
adora list

# 3. Inspect the problem node
adora node info -d my-dataflow problem-node

# 4. Check node resource usage
adora top

# 5. Stream logs from the problem node
adora logs my-dataflow problem-node --follow --level debug

# 6. Is the node producing output?
adora topic echo -d my-dataflow problem-node/output

# 7. Inject test data
adora topic pub -d my-dataflow problem-node/input '[1, 2, 3]'

# 8. Is it publishing at the expected rate?
adora topic hz -d my-dataflow --window 5

# 9. Check/modify runtime parameters
adora param list -d my-dataflow problem-node
adora param set -d my-dataflow problem-node debug_level 2

# 10. Restart a misbehaving node (without stopping the dataflow)
adora node restart -d my-dataflow problem-node

# 11. View coordinator traces (no external infra needed)
adora trace list
adora trace view <trace-id-prefix>

# 12. Visualize the dataflow graph
adora graph dataflow.yml --open

# 13. Record for offline analysis
adora record dataflow.yml -o debug-capture.adorec

录制和回放

录制将实时数据流消息捕获到文件。回放用录制数据替换源节点，让您无需硬件即可复现行为。

录制数据流

# Record all topics (default output: recording_{timestamp}.adorec)
adora record dataflow.yml

# Specify output file
adora record dataflow.yml -o my-capture.adorec

这会向数据流注入一个隐藏的 __adora_record__ 节点，该节点订阅所有节点输出并将其写入 .adorec 文件。录制节点二进制文件（adora-record-node）在首次使用时自动构建。

录制将持续运行，直到按下 Ctrl-C 或数据流停止。

录制特定主题

# Only record camera and lidar
adora record dataflow.yml --topics sensor/image,lidar/points

主题名称使用 node_id/output_id 格式。可用主题可通过 adora topic list -d <dataflow> 查看。

代理录制（远程/无盘）

当目标机器没有本地磁盘或您希望在本地机器上录制时：

# Start the dataflow first (detached)
adora start dataflow.yml --detach

# Record via WebSocket proxy -- data streams through coordinator to CLI
adora record dataflow.yml --proxy -o capture.adorec

# Record specific topics via proxy
adora record dataflow.yml --proxy --topics sensor/image,lidar/points

代理模式工作原理：

  1. 数据流必须已在运行（adora start --detach）
  2. CLI 通过 WebSocket 连接到协调器
  3. 协调器代表 CLI 订阅 Zenoh
  4. 消息数据通过 WebSocket 二进制帧流式传输到 CLI
  5. CLI 在本地写入 .adorec 文件

这需要在描述符中设置 publish_all_messages_to_zenoh: true。

何时使用 --proxy：

  • 无本地磁盘的嵌入式目标
  • 希望在工作站上录制的远程机器
  • 仅有 WebSocket 连接（无直接 Zenoh 访问）时

何时使用默认模式（不带 --proxy）：

  • 同一机器或共享文件系统
  • 高吞吐场景（无 WebSocket 开销）
  • 无需 publish_all_messages_to_zenoh

回放录制

# Replay at original speed
adora replay recording.adorec

# Replay at 2x speed
adora replay recording.adorec --speed 2.0

# Replay as fast as possible (speed 0)
adora replay recording.adorec --speed 0

回放工作原理：

  1. 读取 .adorec 文件头获取原始数据流描述符
  2. 识别哪些节点产生了录制数据
  3. 将这些源节点替换为 adora-replay-node 实例
  4. 运行修改后的数据流 – 下游节点接收的回放数据与实时数据完全相同

回放节点二进制文件（adora-replay-node）在首次使用时自动构建。

回放选项

标志默认描述
--speed <FLOAT>1.0回放速度倍率。2.0 = 2 倍速、0.5 = 半速、0 = 尽可能快
--loopoff连续循环播放录制
--replace <NODES>所有已录制的逗号分隔的要替换的节点列表
--output-yaml <PATH>-写入修改后的描述符 YAML 但不运行

选择性回放

仅替换特定源节点，保持其他节点运行：

# Only replace the sensor node, keep camera live
adora replay recording.adorec --replace sensor

# Replace sensor and lidar, keep everything else live
adora replay recording.adorec --replace sensor,lidar

当您想用已知输入数据调试特定处理流水线同时保持系统其他部分运行时，这很有用。

干运行（输出 YAML）

录制和回放都支持 --output-yaml 来查看修改后的描述符而不运行：

# See what the record-injected descriptor looks like
adora record dataflow.yml --output-yaml record-modified.yml

# See what the replay-modified descriptor looks like
adora replay recording.adorec --output-yaml replay-modified.yml

录制文件格式

.adorec 格式是一个简单的二进制文件：

┌──────────────────────────────────┐
│ Header (bincode)                 │
│   version: u32                   │
│   start_nanos: u64               │
│   dataflow_id: Uuid              │
│   descriptor_yaml: Vec<u8>       │
├──────────────────────────────────┤
│ Entry 1 (bincode)                │
│   node_id: String                │
│   output_id: String              │
│   timestamp_offset_nanos: u64    │
│   event_bytes: Vec<u8>           │
├──────────────────────────────────┤
│ Entry 2 ...                      │
├──────────────────────────────────┤
│ ...                              │
├──────────────────────────────────┤
│ Footer (bincode)                 │
│   total_messages: u64            │
│   total_bytes: u64               │
└──────────────────────────────────┘

event_bytes 字段包含原始的 Timestamped<InterDaemonEvent> bincode 载荷 – 与守护进程之间的线上传输格式相同。头部中的 descriptor_yaml 存储原始数据流描述符，以便回放时重建数据流。

Node Management

Node Info

Get detailed information about a specific node including its status, inputs, outputs, metrics, and restart count:

adora node info -d my-dataflow camera

# JSON output
adora node info -d my-dataflow camera --format json

Node Restart

Restart a single node without stopping the entire dataflow. Useful for recovering a misbehaving node or picking up configuration changes:

# Restart with default grace period
adora node restart -d my-dataflow camera

# Restart with custom grace period
adora node restart -d my-dataflow camera --grace 10s

The daemon sends a stop event, waits for the grace period, then respawns the node process.

Node Stop

Stop a single node without stopping the entire dataflow:

adora node stop -d my-dataflow camera

# With custom grace period
adora node stop -d my-dataflow camera --grace 5s

主题检查

主题检查命令通过协调器的 WebSocket 代理订阅实时数据流消息。需要 --debug 标志或 publish_all_messages_to_zenoh: true。

列出主题

# List all topics in a running dataflow
adora topic list -d my-dataflow

# JSON output
adora topic list -d my-dataflow --format json

显示每个输出、发布它的节点以及订阅它的节点。此命令从描述符读取，不需要 publish_all_messages_to_zenoh。

回显主题数据

将实时主题数据流式输出到终端：

# Echo a single topic
adora topic echo -d my-dataflow camera_node/image

# Echo multiple topics
adora topic echo -d my-dataflow robot1/pose robot2/vel

# JSON output (useful for piping to jq or other tools)
adora topic echo -d my-dataflow robot1/pose --format json

# Echo all topics
adora topic echo -d my-dataflow

每行显示主题名称、Arrow 数据内容和元数据参数。使用 --format json 获取机器可读输出：

{"timestamp":1709000000000,"name":"robot1/pose","data":[1.0,2.0,3.0],"metadata":null}

测量频率

交互式 TUI 显示每个主题的发布频率：

# All topics with 10-second sliding window
adora topic hz -d my-dataflow --window 10

# Specific topics with 5-second window
adora topic hz -d my-dataflow robot1/pose robot2/vel --window 5

TUI 显示：

  • 平均频率 (Hz)
  • 平均、最小、最大间隔
  • 标准差
  • 显示近期活动的火花图

按 q 或 Ctrl-C 退出。需要交互式终端。

Publishing Test Data

Inject data into a running dataflow for testing. Requires publish_all_messages_to_zenoh: true.

# Publish a single Arrow array
adora topic pub -d my-dataflow sensor/threshold '[42]'

# Publish from a JSON file
adora topic pub -d my-dataflow sensor/config --file test-config.json

# Publish multiple messages
adora topic pub -d my-dataflow sensor/trigger '[1]' --count 10

This is useful for:

  • Testing node behavior with known input data
  • Triggering specific code paths in downstream nodes
  • Simulating sensor inputs without hardware

主题元数据与统计

一次性统计采集：

# Collect stats for 5 seconds (default)
adora topic info -d my-dataflow camera_node/image

# Collect for 10 seconds
adora topic info -d my-dataflow camera_node/image --duration 10

Reports:

  • Arrow 数据类型
  • 发布者节点
  • 订阅者节点（来自描述符）
  • 消息计数和带宽
  • 发布频率

Runtime Parameters

Runtime parameters let you read and modify node configuration while a dataflow is running, without restarting. Parameters are stored in the coordinator and optionally forwarded to running nodes.

# List all parameters for a node
adora param list -d my-dataflow detector

# Get a single parameter
adora param get -d my-dataflow detector confidence

# Set a parameter (value is JSON)
adora param set -d my-dataflow detector confidence 0.8
adora param set -d my-dataflow detector config '{"nms": 0.5, "classes": ["car", "person"]}'

# Delete a parameter
adora param delete -d my-dataflow detector confidence

Parameters are persisted in the coordinator store (in-memory or redb). When a node is running, param set also forwards the new value to the node’s daemon. Nodes can read parameters through the node event stream.

Limits: Keys max 256 bytes, values max 64KB serialized.

Environment Diagnosis

adora doctor performs a comprehensive health check of your environment:

# Basic diagnosis
adora doctor

# Diagnosis + dataflow validation
adora doctor --dataflow dataflow.yml

Checks performed:

  1. Coordinator reachability
  2. Connected daemon status
  3. Active dataflow health
  4. Dataflow YAML validation (if --dataflow provided)

Use this as a first step when debugging any issue, or in CI to validate the environment before running tests.

追踪检查

协调器从 adora_coordinator 和 adora_core crate 在内存中捕获追踪 span（环形缓冲区中最多 4096 个 span）。您可以在没有任何外部追踪基础设施的情况下查看这些追踪（无需 Jaeger、Tempo 等）。

列出追踪

adora trace list

显示所有捕获的追踪及其根 span 名称、span 计数、开始时间和总持续时间：

TRACE ID      ROOT SPAN          SPANS  STARTED              DURATION
a1b2c3d4e5f6  spawn_dataflow     12     2026-03-01 10:30:05  1.234s
f8e7d6c5b4a3  build_dataflow     5      2026-03-01 10:29:58  0.500s

查看追踪

# Full trace ID
adora trace view a1b2c3d4-e5f6-7890-abcd-1234567890ab

# Or use a unique prefix
adora trace view a1b2c3d4

以缩进树形式显示 span，展示父子关系、日志级别、持续时间和 span 字段：

spawn_dataflow [INFO 1.234s] {build_id="abc", session_id="def"}
  build_dataflow [INFO 0.500s]
    download_node [DEBUG 0.200s] {url="..."}
  start_inner [INFO 0.734s]
    spawn_node [INFO 0.100s] {node_id="camera"}
    spawn_node [INFO 0.080s] {node_id="detector"}

何时使用追踪检查

  • 快速调试 – 无需设置 Jaeger/Tempo 即可查看协调器在 start、stop 或 build 期间的操作
  • 性能分析 – 识别数据流生命周期操作中的慢 span
  • 部署故障排查 – 了解协调器操作的顺序和时间

要获取跨守护进程和节点的完整分布式追踪，请设置 ADORA_OTLP_ENDPOINT 并使用兼容 OTLP 的后端。

资源监控

adora top（也可用 adora inspect top）提供实时 TUI 显示每个节点的资源使用情况：

# Default 2-second refresh
adora top

# Custom refresh interval
adora top --refresh-interval 5

# JSON snapshot for scripting/CI
adora top --once | jq .

为每个节点显示：

  • CPU 使用率（单核百分比）
  • 内存（RSS）
  • 节点状态（Running、Restarting、Degraded、Failed）
  • 重启次数
  • 队列深度（待处理消息）
  • 网络 TX/RX（通过 Zenoh 的跨守护进程字节数）
  • 磁盘 I/O 读/写

指标由守护进程采集并报告给协调器，因此适用于跨多台机器的分布式数据流。按 q 或 Ctrl-C 退出。

使用 --once 打印单次 JSON 快照并退出，适用于 CI 流水线和监控集成。

注意：CPU 百分比为单核值，因此多线程节点的值可能超过 100%。不同机器上的节点可能有不同的 CPU，因此百分比在跨机器间不可直接比较。

日志分析

实时日志流

# Stream logs from a specific node
adora logs my-dataflow sensor-node --follow

# Stream logs from all nodes
adora logs my-dataflow --all-nodes --follow

# Filter by log level
adora logs my-dataflow sensor-node --follow --level debug

# Stream with grep filter
adora logs my-dataflow --all-nodes --follow --grep "error"

不使用 --follow 时，从本地日志文件读取。使用 --follow 时，通过 WebSocket 从协调器实时流式传输。

本地日志文件

日志存储在 out/ 目录中：

out/
  <dataflow-uuid>/
    log_<node-id>.jsonl          # current log
    log_<node-id>.1.jsonl        # rotated (previous)
    log_<node-id>.2.jsonl        # rotated (older)

直接读取：

# All nodes, local files
adora logs --local --all-nodes

# Specific node, last 50 lines
adora logs --local sensor-node --tail 50

过滤与搜索

标志示例描述
--level <LEVEL>--level debug最低级别：error、warn、info、debug、trace、stdout
--log-filter <FILTER>--log-filter "sensor=debug,processor=warn"按节点级别过滤
--grep <PATTERN>--grep "timeout"不区分大小写的子串匹配
--since <DURATION>--since 5m仅显示此时间之后的日志
--until <DURATION>--until 1h仅显示此时间之前的日志
--tail <N>--tail 100显示最后 N 行
--log-format <FMT>--log-format json输出格式：pretty（默认）或 json

环境变量：

  • ADORA_LOG_LEVEL – 默认日志级别
  • ADORA_LOG_FORMAT – 默认日志格式
  • ADORA_LOG_FILTER – 默认按节点过滤

数据流可视化

生成数据流的可视化图表：

# Generate HTML and open in browser
adora graph dataflow.yml --open

# Generate Mermaid diagram text
adora graph dataflow.yml --mermaid

Mermaid 输出可以粘贴到 mermaid.live 或在 GitHub markdown 中使用：

```mermaid
graph TD
    sensor --> processor
    processor --> controller
```

HTML 模式生成一个包含交互式 mermaid.js 图表的自包含文件。

监控运行中的数据流

# Full environment diagnosis
adora doctor

# List all dataflows (active and completed)
adora list

# List nodes in a specific dataflow
adora node list -d my-dataflow

# Get detailed info on a specific node
adora node info -d my-dataflow camera

# Check coordinator/daemon status
adora status

# View/modify runtime parameters
adora param list -d my-dataflow detector
adora param set -d my-dataflow detector threshold 0.5

adora list 显示每个数据流的 UUID、名称、状态和节点数量。将 -d <name> 与其他命令配合使用以指定特定数据流。

端到端调试工作流

工作流 1：节点未产生输出

# 1. Verify the node is running
adora list
adora top

# 2. Check its logs
adora logs my-dataflow problem-node --follow --level trace

# 3. Check if upstream nodes are publishing
adora topic echo -d my-dataflow upstream-node/output

# 4. Verify topic wiring
adora topic list -d my-dataflow
adora graph dataflow.yml --open

工作流 2：意外数据或错误值

# 1. Echo the topic to see raw data
adora topic echo -d my-dataflow node/output --format json

# 2. Record for offline analysis
adora record dataflow.yml -o debug.adorec

# 3. Replay with known input to isolate the issue
adora replay debug.adorec --replace sensor --speed 0

工作流 3：性能问题

# 1. Check CPU/memory per node
adora top

# 2. Measure publish frequencies
adora topic hz -d my-dataflow --window 10

# 3. Get bandwidth stats for suspected bottleneck
adora topic info -d my-dataflow heavy-node/output --duration 10

# 4. Record and replay at max speed to find throughput limits
adora record dataflow.yml -o perf.adorec
adora replay perf.adorec --speed 0

工作流 4：复现现场问题

# On the robot / target machine:
adora start dataflow.yml --detach
adora record dataflow.yml --proxy -o field-capture.adorec

# Transfer the .adorec file to your workstation, then:
adora replay field-capture.adorec
adora replay field-capture.adorec --speed 0.5  # slow motion
adora replay field-capture.adorec --loop        # continuous replay

工作流 5：远程调试（无直接访问）

当您仅有到协调器的 WebSocket 连接时：

# All these commands work over WebSocket -- no Zenoh needed
adora list
adora top
adora logs my-dataflow --all-nodes --follow
adora topic echo -d my-dataflow node/output
adora topic hz -d my-dataflow
adora record dataflow.yml --proxy -o remote-capture.adorec

另请参阅