Features & Configuration

Capture strategies

The 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 (default: https://api.robotops.com)

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://api.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

systemd service override

To set environment variables for the systemd-managed service:

sudo systemctl edit robot-agent

[Service]
Environment=ROBOTOPS_API_KEY=sk_your_key_here
Environment=RMW_IMPLEMENTATION=rmw_robotops
Environment=ROBOTOPS_UNDERLYING_RMW=rmw_fastrtps_cpp

Reload after changes:

sudo systemctl daemon-reload
sudo systemctl restart robot-agent