Skip to main content

Glossary

Terms used across the TraceHouse ecosystem.

Adaptive Capture​

A TraceHouse Agent capture strategy (implemented by robot-agent, value "adaptive") that dynamically adjusts the sampling rate for each topic based on measured bandwidth. It avoids overwhelming the buffer on high-frequency topics while still capturing meaningful data. See Capture Strategies.

Auto-init (env-default)​

The default way to turn on the RobotOps Trace SDK — the Datadog -javaagent model. Set once in the launch environment, every node auto-instruments with zero per-node code: C++ via LD_PRELOAD=librobotops_trace_autoinit.so (a constructor lib that runs RobotOps::init() on load), Python via ROBOTOPS_TRACE_AUTOINIT=1 (a .pth/sitecustomize hook that calls robotops.init()). Nodes outside that environment can initialize explicitly instead. See Instrumentation.

Black-box Span​

A span for code the SDK observes but has no integration for — it appears in the trace as opaque, with no inner detail. Missing coverage is a gap, never a failure: the SDK never crashes or blocks uninstrumented code. Add the matching integration to see inside.

Carrier​

The role the TraceHouse Agent plays for tracing: it receives spans from the SDK over a local socket and forwards them to TraceHouse. (The agent also independently collects logs, metrics, TF, and MCAP.)

FIFO Buffer​

The TraceHouse Agent's local disk buffer. Stores telemetry in MCAP files when the backend is unreachable. Default size: 500 MB. When full, oldest data is evicted (first-in, first-out). Configurable via ROBOT_OPS_AGENT_BUFFER_MAX_SIZE_MB.

Goal UUID (action stitching)​

The deterministic cross-process join key for ROS 2 actions, carried in the robot.action.goal_id attribute (RFC-4122 UUID), emitted identically on the action client and server. It lets TraceHouse stitch an action call (e.g. NavigateToPose) into a single trace across the process boundary — deterministically, not by content hashing.

MCAP​

A container file format for recording robotics data (multimodal, time-indexed). The TraceHouse Agent uses MCAP for its offline buffer. MCAP files are compatible with Foxglove Studio and other ROS2 tools.

Offline Mode​

The TraceHouse Agent operates without a backend connection: data is buffered locally in MCAP files and uploaded when connectivity is restored. No data is lost during temporary network outages.

OpenTelemetry (OTel) / OTLP​

OpenTelemetry is a vendor-neutral observability standard for traces, metrics, and logs. The RobotOps Trace SDK emits OTel-compatible spans and exports them to the agent using OTLP (the OpenTelemetry Protocol) — HTTP + protobuf over a Unix domain socket by default. ROSQL is built to query OTel-formatted ROS2 traces.

RMW (ROS Middleware)​

The abstraction layer between ROS2 and the underlying DDS implementation. ROS2 supports multiple RMW implementations and selects one via the RMW_IMPLEMENTATION environment variable. (The TraceHouse SDK works above the RMW layer and does not require swapping it.)

rmw_robotops (deprecated)​

The deprecated passive tracing path: a ROS2 RMW shim, enabled with RMW_IMPLEMENTATION=rmw_robotops, that propagated trace context through DDS metadata and published TraceEvent messages. Superseded by the RobotOps Trace SDK, which produces deterministic in-process traces. Frozen, not deleted; no longer installed by default. See Related Libraries.

RobotOps Trace SDK​

The libraries that produce distributed traces from inside your nodes — robotops-trace-cpp (C++), robotops-trace-python (Python), and the robotops-trace-integrations framework hooks (rclcpp, rclpy, BehaviorTree.CPP, ros2_control, MoveIt). They auto-instrument callbacks and actions and export OTLP spans to the carrier. See Instrumentation.

ROSQL​

ROSQL (pronounced "RAW-skul") is an open source SQL-like query language for querying ROS2 telemetry — traces, logs, and metrics — with first-class knowledge of ROS2 concepts like nodes, topics, actions, and message causality. Created and open-sourced by Robot Ops, Inc. Full docs at rosql.org.

Semantic Conventions​

The shared, stable robotics attribute vocabulary that describes spans, defined by the robotops_trace_semconv package. Two namespaces: robot.* — portable robotics concept keys (robot.action.*, robot.callback.type, robot.transform.*, robot.joint.*, robot.trajectory.*, robot.target.*, robot.component.name); and ros.* — the ROS mapping keys present only when the transport is ROS (ros.node, ros.topic, ros.service, ros.message.type, plus the content-correlation keys ros.publisher_gid, ros.source_timestamp, ros.message.content_hash). Resource attributes set once per process include service.name and robot.id.

Span / Span ID​

An individual unit of work in a distributed trace (e.g. "this node processed a message"). Each span has a unique span_id and may have a parent_span_id linking it to the operation that caused it. Span success/failure is carried by the OTel status code; the domain outcome of an action is the separate robot.action.result attribute.

TF Snapshot Deduplication​

A TraceHouse Agent optimization that compares each transform tree snapshot to the previous one and only stores the diff. For stationary robots (or robots with many static transforms), this achieves ~99% storage savings.

Trace / Trace ID​

A distributed trace captures the full causal chain of an operation across multiple ROS2 nodes. All spans belonging to the same logical operation share a trace_id.

TraceHouse Agent​

The on-robot binary (robot-agent) that acts as the carrier for SDK spans and independently collects logs, metrics, TF, and MCAP, streaming everything to TraceHouse. See TraceHouse Agent Overview.

Unix Domain Socket (UDS)​

The default transport for SDK→agent OTLP, at /run/robotops/trace.sock. Lighter than TCP (skips the TCP/IP stack), more secure (filesystem-permission access control, no open local port), and free of port conflicts. The agent's systemd RuntimeDirectory creates and owns the socket; override with ROBOTOPS_OTLP_ENDPOINT for the containerized split.

TraceEvent / TraceContextChange (deprecated)​

Message types defined in robotops_msgs, used by the deprecated passive rmw_robotops pipeline (/robotops/trace_events, /robotops/trace_context). The SDK exports OTLP directly and does not use these messages.