TraceHouse Agent Overview
The TraceHouse™ agent (robot-agent) is a Rust binary that runs on the robot's onboard computer and streams telemetry into TraceHouse. It is the carrier: it receives distributed-trace spans from the RobotOps Trace SDK over a local socket and forwards them, and independently collects logs, metrics, TF, and MCAP. It is designed to be low-overhead, resilient, and safe to run on production robots.
What it collects
| Category | Details |
|---|---|
| Distributed traces | OTLP spans received from the RobotOps Trace SDK over a local Unix socket (/run/robotops/trace.sock) and forwarded to TraceHouse |
| ROS2 topics | Automatically discovers and subscribes to all topics using configurable capture strategies |
| ROS2 logs | Captures the /rosout topic for all ROS2 node logs |
| System logs | Integrates with journald for host-level log collection |
| System metrics | CPU, memory, disk, network quality (latency, jitter, packet loss), temperature, battery, and process list |
| TF transforms | Transform tree snapshots with deduplication (~99% storage savings for stationary robots) |
| MCAP | Records telemetry to MCAP for offline buffering and replay |
:::note Trace source: the SDK, not the RMW shim
Traces now come from the SDK running inside your nodes, not from the deprecated
passive rmw_robotops RMW shim. The agent's log / metric / TF / MCAP collection is
unchanged — only the trace ingestion path moved to OTLP over the local socket.
:::
Architecture
The agent is a standalone Rust binary installed via Debian package and managed by systemd. It:
- Sources the ROS2 environment at startup to discover the running ROS2 graph
- Subscribes to all topics using the configured capture strategy (adaptive, rate-limited, sampled, etc.)
- Buffers data locally in a 500 MB FIFO buffer at
/var/tmp/robot_agent/bufferfor offline resilience - Streams to the backend over gRPC when connectivity is available
- Enters offline mode automatically if the API key is missing or the backend is unreachable — data is preserved and uploaded when the connection is restored
Production readiness
The agent is built for production robot deployments:
- Offline mode: No data loss during network outages — the FIFO buffer holds up to 500 MB (configurable) and uploads automatically when connectivity is restored
- Exponential backoff: Retries failed backend connections with jitter to avoid thundering-herd
- Heartbeat monitoring: Periodic pings detect API key revocations and backend unavailability at runtime
- Minimal footprint: Rust binary with no runtime allocations in hot paths; TF deduplication prevents storage runaway on stationary robots
- Layered configuration: Embedded defaults → YAML file → environment variables (highest priority), making it container and Kubernetes-native
Cross-platform
Supports amd64 and arm64 architectures. Runs on any Ubuntu 24.04 Noble robot regardless of whether it's an x86 server, a Raspberry Pi 5, a Jetson, or a custom arm64 board.
Installation
See the Quickstart for the one-line install command, or System Requirements for architecture and OS details.
What's next
- Features & Configuration — capture strategies, environment variables, YAML config options
- Instrumentation — the SDK that produces the traces this agent carries
- Related Libraries — the Trace SDK, rosql, and the rest of the ecosystem