Features & Configuration

Capture strategies

The TraceHouse™ agent's subscriptions section controls how topic data is captured. You can set a default strategy and override it per topic pattern.

Strategy	Behaviour
adaptive	Adjusts sampling rate dynamically based on measured bandwidth — the default
rate_limit	Publishes at most target_hz messages per second
sample	Keeps every Nth message
all	Captures every message (use with care on high-frequency topics)
on_change	Only captures when the message content changes

Example config:

subscriptions:
  default_strategy: "adaptive"
  default_target_hz: 10.0
  topic_overrides:
    - pattern: "^/camera/.*"
      strategy: "rate_limit"
      target_hz: 2.0         # high-bandwidth cameras: 2 fps max
    - pattern: "^/imu$"
      strategy: "rate_limit"
      target_hz: 50.0        # IMU: full rate
    - pattern: "^/cmd_vel$"
      strategy: "on_change"  # only when velocity changes

Key environment variables

All configuration can be set via environment variables using the ROBOT_OPS_AGENT_ prefix. The most commonly used variables:

Variable	Description
ROBOTOPS_API_KEY	API key for the Robot Ops backend (prefix sk_)
RMW_IMPLEMENTATION	Set to rmw_robotops to enable distributed tracing
ROBOTOPS_UNDERLYING_RMW	The DDS RMW to delegate to (e.g. rmw_fastrtps_cpp)
ROBOT_OPS_AGENT_BUFFER_MAX_SIZE_MB	Local FIFO buffer size in MB (default: 500)
ROBOT_OPS_AGENT_BUFFER_STORAGE_PATH	Buffer storage path (default: /var/tmp/robot_agent/buffer)
ROBOT_OPS_AGENT_SUBSCRIPTIONS_DEFAULT_TARGET_HZ	Default rate limit for rate_limit strategy
ROBOT_OPS_AGENT_LOGGING_CAPTURE_ROSOUT	Capture /rosout logs (true/false)
ROBOT_OPS_AGENT_BACKEND_URL	Backend gRPC endpoint. Set to https://backend.robotops.com (the production endpoint). The compiled-in default still points at the legacy api.robotops.com, so set this explicitly; override it for self-hosted/dev (e.g. http://localhost:50051)

For Docker and Kubernetes deployments, environment variables are the recommended configuration method.

Configuration file

The config file lives at /etc/robotops/config.yaml by default. Override with ROBOTOPS_CONFIG_PATH=/path/to/config.yaml.

Full example:

buffer:
  max_size_mb: 500
  storage_path: "/var/tmp/robot_agent/buffer"

subscriptions:
  default_strategy: "adaptive"
  default_target_hz: 10.0
  topic_overrides:
    - pattern: "^/camera/.*"
      strategy: "rate_limit"
      target_hz: 2.0

metrics:
  enabled: true
  collection_interval_secs: 10
  network_quality_metrics: true

tf:
  enabled: true
  deduplication: true          # ~99% savings for stationary robots

system_logs:
  enabled: true
  journald:
    min_priority: "warning"

logging:
  capture_rosout: true
  level: "info"

backend:
  url: "https://backend.robotops.com"
  heartbeat_interval_secs: 30
  max_retry_attempts: 5
  initial_backoff_secs: 1
  max_backoff_secs: 60

API key security

The agent supports three methods for providing the API key (highest to lowest precedence):

1. Environment variable (recommended):

   export ROBOTOPS_API_KEY="sk_your_key_here"

2. File (for secrets management):

   # /etc/robotops/config.yaml
   auth:
     api_key_file: "/run/secrets/robotops_api_key"

   The file should be chmod 600. The agent warns if permissions are wider.

3. Inline config (not for production):

   auth:
     api_key: "sk_your_key_here"

API keys are never logged — they appear as sk_***...*** in all output.

Offline mode

When the API key is missing or the backend is unreachable, the agent enters offline mode automatically:

• Telemetry is written to local MCAP files under the configured buffer path
• The FIFO buffer holds up to 500 MB (configurable) and evicts old data when full
• Data is uploaded automatically when connectivity is restored — no data is lost
• The agent sends periodic heartbeats to detect connectivity changes at runtime

Applying environment variables

The agent reads the same variables no matter how it's launched. Use whichever model fits your deployment (the Quickstart walks through all three).

On-host (systemd) — set them in a service override:

sudo systemctl edit robot-agent

[Service]
Environment=ROBOTOPS_API_KEY=sk_your_key_here
Environment=ROBOT_OPS_AGENT_BACKEND_URL=https://backend.robotops.com
Environment=RMW_IMPLEMENTATION=rmw_robotops
Environment=ROBOTOPS_UNDERLYING_RMW=rmw_fastrtps_cpp

sudo systemctl daemon-reload
sudo systemctl restart robot-agent

Container (Docker) — pass them with -e (no systemd inside containers):

docker run -e ROBOTOPS_API_KEY=sk_your_key_here \
           -e ROBOT_OPS_AGENT_BACKEND_URL=https://backend.robotops.com \
           -e RMW_IMPLEMENTATION=rmw_robotops \
           -e ROBOTOPS_UNDERLYING_RMW=rmw_fastrtps_cpp \
           your-image robot-agent

ROS launch file — set RMW_IMPLEMENTATION for traced nodes with a SetEnvironmentVariable action, and start the agent as a process from the same launch.