Device configuration

​

At a glance

The device Config tab has three sections in the left sidebar:

• Overview: device name, type and description. The device’s tags are shown at the top of the device page.
• Data Collection: every topic the device publishes, and what the platform does with each one.
• Open Telemetry: the OTel inventory and ingestion toggle.

​

Status indicator

The status badge on the device header shows whether the device is currently online or offline. This status refreshes automatically so you can see near-real-time connectivity without reloading the page. If the device shows “Offline”:

• Check the device’s network and power.
• If problems persist, see the Troubleshooting section below or contact your administrator.

​

Data Collection

A device can do two different things with a topic, and they are independent:

• Monitor: ingest it as live telemetry for dashboards, queries and alarms.
• Record: write it to MCAP files in the on-device rolling buffer for later playback and upload.

The table shows one row per topic with a checkbox in each column, so a topic can be monitored, recorded, both, or neither. A Rate column next to them shows how fast each topic is publishing on the robot. Click Edit to make changes, then Save configuration. The save bar at the bottom shows the running totals and exactly what you changed (for example +3 monitoring, -1 recording) before you commit. Saving pushes the new configuration to the agent automatically, with no need to restart the agent or the device.

​

Stopping and starting monitoring

You can stop all live monitoring on a device without touching its configuration, for example while a robot is in maintenance, on a metered link, or parked for the night. Monitoring is on for every device until you stop it. To stop it, open the ⋮ menu in the device header and choose Stop monitoring. You’ll be asked to confirm first, because stopping cuts every live data stream from the device at once. While monitoring is stopped:

• No host metrics, monitored ROS 2 topics or OpenTelemetry data reach the cloud. Dashboards for the device go quiet, and alarms that read its telemetry stop evaluating.
• Recording keeps running. The rolling buffer, recording rules and uploads carry on exactly as before.
• Your topic selection stays as it is. The Monitor checkboxes keep their ticks, and you can still edit them.
• The device stays online. Its status comes from the agent’s connection, not from telemetry.

The device header shows the monitored count as (stopped), and a banner at the top of Data Collection says monitoring is stopped. Click Start monitoring in the banner, or in the header menu, and the selected topics start streaming again shortly. You don’t need to restart the agent. To stop or start several devices at once, see Devices overview.

Note: Stopping and starting monitoring works on any agent version. From agent 1.0.0, the agent also stops sending host metrics, so a stopped device uses no network for telemetry. Older agents keep sending host metrics, and the platform discards them.

​

Finding topics

• Search filters by topic name.
• Filter chips narrow the list to All, ROS 2, Host metrics, Monitoring, Recording or Unassigned. Unassigned is the quickest way to spot topics nothing is collecting yet.
• Topics are grouped by namespace (/camera, /nav, and so on). Devices with more than 40 topics open with groups collapsed.
• The checkbox on a group header applies to every topic beneath it, so you can turn on a whole namespace in one click. It shows a dash when only some of the group is selected.
• Expanding a row shows the message fields the topic carries. Selecting a topic always captures all of its nested fields; there is no per-field selection.

​

Rate column

The Rate column shows how many messages per second each topic is publishing, measured on the robot, next to the rate it is expected to run at: 20.0 Hz / 30.0 means 20 Hz measured against 30 Hz expected. The rate is the topic’s own rate:

• The agent measures each message as it arrives, before any downsampling, so a topic downsampled to 2 Hz for telemetry still shows its real 30 Hz.
• The agent never reads the messages to measure them, so measuring costs almost nothing, even on a camera stream.
• The agent measures every topic it receives, whether it is monitored, recorded, or both. It sends a new measurement every 5 seconds, and the column refreshes on its own.

The dot in front of the rate tells you how the topic is doing:

​

Expected rate

ROS 2 topics don’t declare the rate they publish at, so the expected rate is worked out automatically, in this order:

1. The rate you set for the topic, if any.
2. The publisher’s QoS deadline, when the publishing node declares one. A 100 ms deadline means 10 Hz.
3. The usual rate: the median rate over the last 24 hours, leaving out idle periods. Most topics use this one, and it needs no setup.

To set it yourself, click the rate and type the expected rate in Hz. Clearing the field goes back to the automatic value, which the field shows as its placeholder.

​

More statistics

Hover a rate to see everything the agent measured for the topic in its latest 5 seconds:

• Longest gap between two messages, the clearest sign of a stall or a dropout.
• Jitter: how much the time between messages varies.
• Age on arrival: how long a message took from the publisher to the agent.
• Lost: messages the publisher sent that the agent never received, for example on a congested network.
• Publishers on the topic.
• Throughput in bytes per second.

Age and lost messages need ROS 2 Jazzy or later, and lost messages also need a middleware that reports them, such as Fast DDS. On Humble they are left out.

​

Measuring a topic without sending it

Sometimes you only need to know a topic is healthy, not its data: is the camera still at 30 Hz? For a topic that is neither monitored nor recorded, click its rate and tick Measure without sending data.

• The agent then measures the topic for 10 seconds of every minute and sends only the statistics, never the messages, so it costs little even for a camera.
• The topic gets a blue dot in the table.
• Monitored and recorded topics are always measured, so the option doesn’t apply to them.

Note: The Rate column needs agent 1.2.0 or later. Older agents report the rate of monitored topics only, and none of the other statistics.

​

Monitor column

Ticking Monitor ingests the topic as live telemetry. Two kinds of row cannot be changed:

• Host metrics (/host_metrics/*) are always collected while the agent runs and monitoring is on. They show a padlock and cannot be switched off one by one.
• Heavy message types cannot be ingested as telemetry and show a crossed-out checkbox: sensor_msgs/msg/Image, sensor_msgs/msg/CompressedImage, sensor_msgs/msg/PointCloud, sensor_msgs/msg/PointCloud2, nav_msgs/msg/OccupancyGrid and tf2_msgs/msg/TFMessage. These are exactly the topics worth recording, so their Record checkbox stays available.

​

Messages too large for live telemetry

Live telemetry is meant for small messages. The agent doesn’t send any single message larger than 64 KiB as live telemetry, so one oversized topic can’t clog the robot’s link or fill its telemetry buffer during an outage. Recording isn’t affected, and you can record the same topic at any size. When this happens, the Data Collection page tells you:

• A banner above the table counts the monitored topics that are losing messages.
• The topic row shows dropped · too large when every message is over the limit, so no live telemetry arrives, or some dropped · too large when only the larger messages are dropped and the chart has gaps.
• Hovering the badge shows the size the messages reach and the limit.

The usual fix is to stop monitoring the topic and record it instead. If you really need it as live telemetry, the limit can be raised on the robot with the INSAION_METRICS_MAX_MESSAGE_BYTES setting (see Agent Operations).

​

Downsampling

High-rate topics do not need to be stored at full rate. While editing, hover a monitored topic and click the gauge icon to choose:

• No downsampling: store every message.
• Stride (every N): keep one message out of every N.
• Max rate (Hz): keep at most N messages per second.

The active setting appears as a small badge on the row (1/5, 2 Hz). Downsampling applies to monitored telemetry only, not to recordings.

​

Record column

Ticking Record adds the topic to the rolling buffer. The Record checkbox has four states, because recording is driven by patterns as well as individual ticks: Host metrics come from the agent’s own collector rather than the ROS graph, so they cannot be recorded.

​

Rules

The Rules strip above the table records whole groups of topics with one pattern:

• Type a glob such as /camera/* and press Enter, or use Record everything to add *.
• * matches any run of characters including /, so /camera/* also matches /camera/depth/points.
• Every topic a rule matches shows an asterisk in the Record column.

Turning off a rule-matched topic does not delete the rule. It adds an exclusion for that one topic, so the rest of the pattern keeps recording. Ticking it back on removes the exclusion. This means you can say “record all of /camera/* except the point cloud” without listing every topic by hand. An exclusion written as a pattern (rather than a single topic) can only be removed from the Rules strip. Those rows show a disabled checkbox that explains which rule is holding the topic out.

​

Topics that are not currently published

Topics that exist in the saved configuration but that the device is not publishing right now, because it is offline or a node has not started, appear in a Not currently published group at the bottom of the table, marked offline. They are shown rather than hidden so that saving an offline device’s configuration cannot silently drop them.

​

Rolling buffer settings

The Rolling buffer settings panel above the table holds everything about recording that is not per-topic. The Recording switch sits in the panel header so you can see and change it without expanding, and the collapsed header summarises the policy, quota, number of recording sets and upload policy, for example FIFO · 1.0 GB · 1 set · uploads share the link.

• Recording: whether the rolling buffer runs at all. If you select topics but leave this off, the page warns you that nothing will be captured and offers to switch it on.
• Policy: how data is retained once the quota is full:
  • FIFO: the oldest recordings are deleted (recommended for most users).
  • HARD: recording stops.
  • NONE: no limit; use with caution.
• Size (GB): maximum on-device storage for recordings, 1 GB by default. Not applicable when the policy is NONE.
• Recording sets: each set records its own selection of topics into its own MCAP recordings. Click a set’s name to rename it.
• Uploads: how recording uploads use the robot’s network link (agent 1.0.0 or later, see below).

Most devices need only one recording set, and one is created for you the first time you tick a Record checkbox. When more than one set exists, chips above the table choose which one the Record column writes to, and rows carry a small +n badge when other sets also capture that topic. Uploads send the lightest sets first, so keeping small, high-value topics (/tf, odometry, diagnostics) in their own set lets you open them before a camera set has finished uploading.

​

How the agent records

From agent 1.0.0, recordings are written to the rolling buffer about once a second, however much data there is. You don’t pick a file length any more. A sudden power cut loses a second or two at most, and that holds for slow topics as much as busy ones. Camera frames, point clouds and other large messages are stored as they arrive. On slow storage such as an SD card, the agent detects the slow writes and groups data into larger blocks so it keeps up. Older agents split each recording set into files of a fixed length. For devices running an agent older than 1.0.0, each set still shows a Split every N s field (60 s by default); a shorter split limits how much data is at risk if the robot loses power. The field is hidden for agents 1.0.0 and later, which ignore it.

​

Uploads

The Uploads section controls how uploads share the robot’s network link with everything else it sends. It needs agent 1.0.0 or later.

• Leave room for other traffic (on by default, recommended): uploads go as fast as the link allows, and slow down as soon as they start delaying anything else on it, such as live telemetry, teleoperation, a VPN or other software on the robot. Only turn it off on a link used for nothing but uploads.
• Max upload speed (Mbit/s): a hard limit, for metered or shared links such as a cellular plan. Leave it empty for no limit. The minimum is 0.1 Mbit/s.

The two work together: with both set, uploads never exceed the cap and still give way to other traffic below it.

Note: The rolling buffer requires agent version 0.7.0 or later. On older agents the Record column and the settings panel are hidden and the page explains how to upgrade. Monitoring works on any agent version. Upload settings and once-a-second recording need agent 1.0.0 or later.

​

Templates

Two buttons in the Data Collection header let you reuse a configuration:

• Assign Template applies a saved template to this device.
• Export Template saves this device’s current monitoring and recording configuration as a new template. The dialog previews exactly what will be captured before you name it.

When a device is managed by a template, a single row above the table replaces the Edit button:

• The template name, with a padlock, since the table is read-only.
• Auto-update: when on, edits to the template are applied to this device automatically. When off, the device keeps the configuration it has until the template is applied again.
• Edit template: opens the template, affecting every device that uses it.
• Detach: stops following the template and drops into edit mode so you can configure this device on its own. The device keeps its current configuration; detaching changes nothing about what it collects.

See Templates for creating and editing them.

​

Tags

Software versions, serial numbers, hardware revisions and other facts about a device are kept as tags, shown at the top of the device page next to the tags the agent detects. Each tag keeps a history of its values. See Tags.

​

Example use cases

• Dashboards and alarms: monitor /battery_state and /cmd_vel, and downsample a chatty /odom to 2 Hz.
• Sensor health: tick Measure without sending data on /camera/image_raw to see it drop below 30 Hz without streaming a single frame.
• Incident playback: record /camera/* and /velodyne_points with a rule, even though they cannot be monitored as telemetry.
• Debugging: use Record everything temporarily to capture the last hour of everything the robot publishes.
• Compliance: keep a rolling window of operational data with a FIFO policy and a fixed quota.

​

Best practices

• Give devices meaningful names (ID + role, e.g. “AMR Sector 4B”) so they are easy to find.
• Monitor what you want to chart or alarm on; record what you want to replay. Heavy sensor topics belong in the Record column.
• Prefer a rule such as /camera/* over ticking twenty individual topics. It keeps working when the robot gains a new camera topic.
• Keep the quota size reasonable to avoid filling device storage. With FIFO, the quota decides how far back you can still upload: at about 2 MB/s of camera data, 1 GB holds roughly 8 minutes.
• On a cellular or shared link, keep Leave room for other traffic on, and add a Max upload speed if the data plan is metered.
• Use the Unassigned filter after onboarding a device to check nothing important was missed.
• Set the expected rate on the few topics that matter most, such as cameras, lidars and odometry, so an amber dot means a real problem rather than a change in the usual rate.
• Once a device is configured the way you want, use Export Template so the next device takes one click.

​

Troubleshooting

• A topic is missing from the table. The agent only lists topics it has seen. Check the node is publishing, then reload.
• A Record checkbox will not turn on. A pattern exclusion is holding it out; remove that rule from the Rules strip.
• Nothing arrives from any topic. Check whether monitoring is stopped: the header shows (stopped) next to the monitored count. Start it from the banner or the header menu.
• A topic is ticked but no data arrives. Confirm the schema type is supported for monitoring, and check the save actually completed. A dropped · too large badge means its messages are over the live telemetry size limit: record the topic instead.
• A topic’s rate shows amber. Hover it to see the longest gap and lost messages. A long gap points at the publishing node stalling; lost messages point at the network or an overloaded robot.
• The Rate column shows no value for a topic. The agent only measures topics it receives: monitor or record the topic, or tick Measure without sending data. Check the agent is 1.2.0 or later.
• Recording is configured but nothing is captured. Check the Recording switch in the rolling buffer header, and that the quota is not full with a HARD policy.