Skip to main content
Version: 0.3

Cookbook

Practical query recipes for common ROS2 observability tasks. Copy, adapt, and run against your telemetry data.

Basic queries​

Find all error spans​

FROM traces WHERE status = 'ERROR'

Error logs at a specific severity​

FROM logs WHERE severity = 'ERROR'

Slowest actions (last hour)​

SELECT span_name, duration
FROM traces
WHERE action_name = '/navigate_to_pose' AND duration > 500 ms
SINCE 1 hour ago
ORDER BY duration DESC
LIMIT 20

Filter by ROS2 node​

FROM traces WHERE node = '/bt_navigator'

Robot-scoped query​

FOR ROBOT 'robot_sim_001' FROM logs WHERE severity = 'ERROR'

Read topic messages​

FROM topics WHERE topic_name = '/battery_state' AND fields['percentage'] < 20

Topic alias​

-- Shorthand for: FROM topics WHERE topic_name = '/odom'
FROM odom LIMIT 5

Cross-signal correlation​

SELECT trace_id, span_name_col, service_name, duration, status_code, span_attributes
FROM traces
WHERE status = 'ERROR' AND action_name = '/navigate_to_pose'
DURING(
  FROM topics WHERE topic_name = '/battery_state'
  AND fields['percentage'] < 15
)
SINCE 6 hours ago

Errors during high CPU load​

FROM traces WHERE status = 'ERROR'
DURING(
  FROM metrics WHERE metric_name = 'system.cpu.total_usage_pct'
  AND metric_value > 90
)
SINCE yesterday

Causality and message tracing​

Trace full message causality chain​

MESSAGE JOURNEY FOR TRACE 'a3f1c9d2e8b04f7a'

Returns all spans in the causal chain by walking parent_span_id → span_id recursively.

Find message paths for a topic​

MESSAGE PATHS FOR TOPIC '/cmd_vel'

Shows which nodes published and subscribed to /cmd_vel.

All spans for a specific trace​

TRACE 'trace-002'

Robot health and anomaly detection​

Robot health assessment​

HEALTH() FOR ROBOT 'robot_sim_001'

Fan-out across traces, logs, and metrics to produce an overall health assessment.

Detect statistical anomalies in span duration​

ANOMALY(duration)

Uses z-score (AVG/STDDEV) to find outlier spans — spans whose duration deviates significantly from the mean.

Path deviation​

PATH DEVIATION FOR ROBOT 'robot_sim_001'

Queries /odom trajectory data from topic_messages to detect if the robot deviated from its planned path.

MCAP recordings​

SHOW RECORDING was never implemented

SHOW RECORDING was reserved syntax in v0.3 but the compiler never supported it. Use FROM recordings (available in v0.4+) to query recording metadata.

Pipeline syntax​

Pipeline syntax uses | to chain stages, making complex queries more readable:

Find slow error spans, grouped by robot​

FROM traces
| WHERE duration > 500 ms
| WHERE status = 'ERROR'
| FACET robot_id
FROM traces
| WHERE action_name = '/navigate_to_pose'
| WHERE status = 'ERROR'
| FACET robot_id
| COMPARE TO last week

Log analysis with ordering​

FROM logs
| WHERE severity IN ('ERROR', 'WARN')
| ORDER BY severity DESC
| LIMIT 20

Time-series and aggregations​

Average span duration per robot​

SELECT AVG(duration) FROM traces FACET robot_id

Error count by severity​

SELECT COUNT(*) FROM logs WHERE severity = 'ERROR' FACET robot_id

Percentile latency for navigation​

SELECT PERCENTILE(duration, 95) FROM traces WHERE action_name = '/navigate_to_pose'

Multiple aggregations​

SELECT AVG(duration) AS avg_dur, MAX(duration) AS max_dur, COUNT(*) AS total FROM traces

See also​