# Installation
Source: https://docs.insaion.com/agent/installation
The Insaion Agent can be installed as a Linux `systemd` service on the target device, or run as a Docker container. The systemd installation is the standard method for robots, gateways, and edge computers running Ubuntu. Docker installation is available for containerized deployments.
For systemd: The installer configures the machine, installs the agent, enables the service, and starts it automatically.
For Docker: Copy and run a generated `docker run` command with your configuration options.
## Installation methods
### Systemd installation
After installation, the device has:
* A background service: `insaion-agent.service`
* A runtime configuration file: `/etc/default/insaion-agent`
* Persistent agent state: `/var/lib/insaion-agent`
### Docker installation
After running the docker command, you have:
* A running container named `insaion-agent`
* Volume mounts for persistent state (`/var/lib/insaion-agent`), system access (`/proc`, `/sys`, `/dev`), and optional ROS workspaces
* Environment variables for registration and ROS configuration
## Supported environment
### Systemd installation
* Ubuntu Linux with `systemd`
* Ubuntu `22.04`, `24.04` and `26.04` for generic host installs
* ROS2-enabled Ubuntu systems, where the installer detects the installed ROS environment and configures the matching agent package automatically
* Outbound internet access to Insaion services and package repositories
* `sudo` or root access
### Docker installation
* Linux host with Docker installed and running
* Any Ubuntu, Debian, or compatible Linux distribution
* Outbound internet access to Insaion services and container registries
* Docker socket access (for running as privileged container)
* Optional: GPU support with nvidia-docker or `--gpus` flag
## Recommended workflow
1. In the Insaion web app, go to Devices and click Add Device.
2. Choose your installation method: **Ubuntu (systemd)** or **Docker**.
3. Select an existing enrollment key, or create a new one on the spot.
4. Switch on any optional settings: ROS distribution, custom workspace, DDS middleware, etc.
5. Copy the generated installation command.
6. Run that command on the target machine.
7. Watch the **Agent status** block on the same page — it reports when the agent has registered, connected, and discovered topics.
### The Add Device page
Everything happens on one page: pick the installation method, then scroll. The install command updates live as you change options, and the page detects your device once the agent comes online.
## Install the agent
### Systemd installation
The installer used by the dashboard is:
```bash theme={null}
curl -fsSL https://get.insaion.com/setup.sh | sudo bash
```
The Add Device page generates the same command with your enrollment key and any ROS or DDS options inline. For example:
```bash theme={null}
curl -fsSL https://get.insaion.com/setup.sh | sudo ENROLLMENT_KEY="your-enrollment-key" bash
```
Run the exact command shown in the dashboard on the target machine.
### Docker installation
The Add Device page generates a complete `docker run` command with your configuration. For example:
```bash theme={null}
docker run -d \
--name insaion-agent \
--network host \
--pid host \
--cap-add=NET_RAW \
--gpus all \
-v /dev/shm:/dev/shm \
-v /proc:/host/proc:ro \
-v /sys:/host/sys:ro \
-v /etc:/host/etc:ro \
-v /var/lib/insaion-agent:/var/lib/insaion-agent \
-e ENROLLMENT_KEY="your-enrollment-key" \
-e RMW_IMPLEMENTATION="rmw_cyclonedds_cpp" \
ghcr.io/insaion/agent:latest-jazzy
```
Run the exact command shown in the dashboard on your Docker host.
## What happens during installation
### Systemd installer
When you run the installer, it automatically:
* Detects whether the machine is a generic Ubuntu system or a ROS2-based system
* Configures the required package repositories
* Installs agent dependencies
* Writes installation-time settings into `/etc/default/insaion-agent`
* Installs the Insaion Agent package
* Enables and starts `insaion-agent.service`
For most users, that is the entire installation process.
### Docker container startup
When you run the docker command, it:
* Pulls the container image (if not already present)
* Creates a container named `insaion-agent`
* Mounts required system volumes for hardware access and ROS network configuration
* Mounts persistent storage for agent state
* Applies environment variables for registration and ROS configuration
* Starts the container in the background
The agent comes online immediately once the container is running.
## Registration method
Devices register using an enrollment key.
### Enrollment Key
Use enrollment keys for production deployments, golden images, scripted provisioning, and fleet rollout.
Read more on the [Add device](../devices/add-device) page.
#### Enrollment steps
1. In the dashboard, open Devices → Add Device.
2. Select an existing enrollment key, or create a new one on the page.
3. Copy the generated install command.
4. Run the command on the device.
5. The installer stores the enrollment key in `/etc/default/insaion-agent`, starts the systemd service, and the agent attempts automatic registration.
6. After successful registration, the device appears in the Devices page.
#### Verify enrollment
```bash theme={null}
sudo systemctl status insaion-agent
sudo journalctl -u insaion-agent -f
```
If the key is valid and the device has network access, you should see the device appear in the web app shortly after the service starts.
After the device is registered, use [Agent Operations](/agent/operations) for service management, configuration, logs, support bundles, updates, and troubleshooting.
## Verify installation
### Systemd
Use the following checklist after install:
* `sudo systemctl status insaion-agent` shows the service as running
* `sudo journalctl -u insaion-agent -f` shows normal startup logs
* The device appears on the Devices page after registration
### Docker
Use the following checklist after running the container:
* `docker ps | grep insaion-agent` shows the container as running
* `docker logs insaion-agent` shows startup logs with no errors
* The device appears on the Devices page after registration
* Check that `/var/lib/insaion-agent` on the host has writable permissions for the container
## Docker-specific considerations
### Required volumes and capabilities
The generated docker command includes specific mounts and capabilities needed for the agent to function:
* **`--network host`**: Allows the agent to communicate with the robot's ROS network
* **`--pid host`**: Host PID namespace sharing for monitoring host processes
* **`--cap-add=NET_RAW`**: Required for certain network operations
* **`--gpus all`**: Passes GPU devices to the container (if available)
* **`-v /dev/shm:/dev/shm`**: Shared memory for ROS communication
* **`-v /proc:/host/proc:ro`**: Host process information (read-only)
* **`-v /sys:/host/sys:ro`**: Host system information (read-only)
* **`-v /etc:/host/etc:ro`**: Host etc directory (read-only)
* **`-v /var/lib/insaion-agent:/var/lib/insaion-agent`**: Persistent agent state
### Custom workspace volumes
If you specify a custom ROS workspace directory when running on Docker, the generated command automatically adds a mount for it:
```bash theme={null}
-v /home/robot/ros2_ws:/home/robot/ros2_ws:ro
```
This allows the container to access the workspace setup scripts on the host.
### Persistent state
The container must have a writable volume for `/var/lib/insaion-agent`. Ensure the host path (`/var/lib/insaion-agent` by default) has appropriate permissions for the container processes to write state files.
For ongoing management or issue resolution, see [Agent Operations](/agent/operations).
# Agent Operations
Source: https://docs.insaion.com/agent/operations
Manage, configure, diagnose, update, and troubleshoot an installed Insaion Agent.
Use this page after installing the Insaion Agent. It covers routine service management, configuration changes, logs, support bundles, updates, and troubleshooting for systemd and Docker deployments.
## Service management
### Systemd
The agent runs as `insaion-agent.service`:
```bash theme={null}
sudo systemctl status insaion-agent
sudo systemctl restart insaion-agent
sudo systemctl stop insaion-agent
sudo systemctl start insaion-agent
```
### Docker
Manage the container with standard Docker commands:
```bash theme={null}
# Check status
docker ps -a --filter name=insaion-agent
# Restart, stop, or start
docker restart insaion-agent
docker stop insaion-agent
docker start insaion-agent
```
## Configure the agent
### Systemd
Runtime configuration is stored in `/etc/default/insaion-agent`. Edit the file and restart the service to apply changes:
```bash theme={null}
sudo nano /etc/default/insaion-agent
sudo systemctl restart insaion-agent
```
### Docker
Docker configuration is supplied through environment variables. To make a persistent change, stop and remove the container, then run the command generated by the Add Device page again with the updated values:
```bash theme={null}
docker stop insaion-agent
docker rm insaion-agent
# Run the updated docker command from the Add Device page.
```
Removing the container does not remove agent state stored in the mounted `/var/lib/insaion-agent` host directory.
### Common variables
* `ENROLLMENT_KEY`: automatically register the device
* `ROS_DISTRO`: ROS2 distribution sourced before launch
* `CUSTOM_ROS_SETUP`: path to an additional ROS workspace setup script
* `RMW_IMPLEMENTATION`: DDS middleware selection, such as CycloneDDS or Fast DDS
* `ROS_DOMAIN_ID`: ROS domain ID for discovery isolation
* `ROS_AUTOMATIC_DISCOVERY_RANGE`: ROS discovery range
* `ROS_STATIC_PEERS`: static peer list for ROS discovery
* `ROS_LOCALHOST_ONLY`: restrict ROS traffic to localhost when required
* `FASTRTPS_DEFAULT_PROFILES_FILE`: Fast DDS profile path
* `ROS_DISCOVERY_SERVER`: Fast DDS discovery server address
* `CYCLONEDDS_URI`: CycloneDDS configuration URI
* `ZENOH_ROUTER_CONFIG_URI`: Zenoh router configuration location
* `ZENOH_SESSION_CONFIG_URI`: Zenoh session configuration location
* `ZENOH_ROUTER_CHECK_ATTEMPTS`: retry count for Zenoh router availability checks
## Logging and diagnostics
The agent uses a standardized log format across its components. Each record includes a timestamp, severity level, and thread identifier. Persistent agent logs also include the source file and line number. Output from managed Telegraf and ReductStore processes is captured in the same stream with a component tag, making events easier to follow in chronological order.
For systemd, follow live service logs with:
```bash theme={null}
sudo journalctl -u insaion-agent -f
```
For Docker, use:
```bash theme={null}
docker logs -f insaion-agent
```
The agent also keeps rotating logs and recent diagnostic snapshots under `/var/lib/insaion-agent/`. Mount this directory as persistent storage in Docker to retain diagnostics across container restarts.
### Create a support bundle
When reporting an issue, generate a redacted support bundle:
```bash theme={null}
sudo insaion-agent --support-bundle
```
The command requests a fresh diagnostic snapshot without stopping the running service. It writes a compressed `.tar.gz` archive to `/tmp` and prints the full path when complete.
Choose a specific output path with:
```bash theme={null}
sudo insaion-agent --support-bundle --output /tmp/insaion-support.tar.gz
```
The bundle includes available agent and service logs, runtime status, recent failure and shutdown diagnostics, host health information, Telegraf configuration, and ROS2 graph information when ROS2 is enabled. Configuration secrets are replaced with `[REDACTED]`, and device tokens are not included. Review the archive before attaching it to an issue or sending it to Insaion support.
For Docker, create the bundle inside the container and copy it to the host:
```bash theme={null}
docker exec insaion-agent insaion-agent --support-bundle --output /tmp/insaion-support.tar.gz
docker cp insaion-agent:/tmp/insaion-support.tar.gz ./insaion-support.tar.gz
```
## Update the agent
### Systemd
If the Insaion package repository is still configured, update the agent with the standard system upgrade workflow:
```bash theme={null}
sudo apt update
sudo apt upgrade
```
This upgrades the agent together with other eligible system packages. The package preserves `/etc/default/insaion-agent` and the state stored under `/var/lib/insaion-agent`, then restarts the service after the agent upgrade.
You can also re-run the installation command generated by the Add Device page. This is useful when you want to update only the agent or restore its package repository configuration.
If APT keeps the agent back or reports a Telegraf version conflict, re-run the current installation command to remove package holds created by older installer versions, then run the upgrade again.
### Docker
Pull the current image and recreate the container with the same configuration and persistent state mount:
```bash theme={null}
docker stop insaion-agent
docker rm insaion-agent
docker pull ghcr.io/insaion/agent:latest-jazzy
# Run the updated docker command from the Add Device page.
```
Replace `latest-jazzy` with the image tag used by your deployment.
## Troubleshooting
### The service or container is not running
For systemd:
```bash theme={null}
sudo systemctl status insaion-agent
sudo journalctl -u insaion-agent --since "30 minutes ago" --no-pager
```
For Docker:
```bash theme={null}
docker ps -a --filter name=insaion-agent
docker logs insaion-agent --tail 100
```
### The device does not register automatically
Confirm that `ENROLLMENT_KEY` is present in the systemd configuration:
```bash theme={null}
sudo grep '^ENROLLMENT_KEY=' /etc/default/insaion-agent
sudo systemctl restart insaion-agent
```
For Docker, verify that the variable was supplied to the container:
```bash theme={null}
docker inspect insaion-agent | grep ENROLLMENT_KEY
```
If it is missing, recreate the container using the command from the Add Device page.
### Custom ROS messages are missing
Set `CUSTOM_ROS_SETUP` to the workspace `setup.bash` path. For Docker, also mount that workspace into the container at the configured path. Restart or recreate the agent after the change.
### DDS settings are not applied
Check the configured middleware variables and verify that referenced files exist:
```bash theme={null}
sudo grep -E 'RMW_IMPLEMENTATION|CYCLONEDDS_URI|FASTRTPS' /etc/default/insaion-agent
ls -la /path/to/dds/config/file
```
For Docker, confirm that the same paths are mounted inside the container.
### Docker state is not persisting
Confirm that `/var/lib/insaion-agent` is mounted and writable on the host:
```bash theme={null}
docker inspect insaion-agent | grep -A 5 '/var/lib/insaion-agent'
ls -la /var/lib/insaion-agent
sudo touch /var/lib/insaion-agent/test && sudo rm /var/lib/insaion-agent/test
```
If an issue remains unresolved, create a support bundle and include it with the issue report.
# Agent Overview
Source: https://docs.insaion.com/agent/overview
The Insaion Agent is a lightweight, secure runtime that runs on your robots and edge devices to connect ROS2-based systems with the Insaion cloud. It is typically installed as a Linux systemd service, and it collects telemetry, forwards selected ROS2 topics and logs, and enforces local configuration and storage policies.
This page gives a high-level view of what the agent does, how it's structured, and where to find installation and configuration details.
## Why run the Insaion Agent?
* Seamless integration with ROS2: the agent is built to coexist with your ROS2 ecosystem (topics, parameters and lifecycle)
* Reliable telemetry and logs: buffered and resumable uploads to tolerate intermittent connectivity
* Secure enrollment & device identity: enrollment keys for safe fleet registration
* Extensible: components for custom telemetry, alarms and integrations
## Key features
* Telemetry collection: topic sampling, custom metrics, periodic system health checks, and host metrics (CPU, memory, network, GPU, disk)
* Device enrollment: automatic registration via `ENROLLMENT_KEY` through the installed agent service
* Standardized diagnostics: consistent timestamps, severity levels, and source context across agent, Telegraf, and ReductStore logs
* Support bundles: a single CLI command collects a redacted diagnostic archive for issue reports
* Lightweight runtime: minimal dependencies, small installer bundles for common ROS2 distros
## Architecture (high-level)
* cpp\_agent: core native component that bridges ROS2 and the agent runtime (publishes status, subscribes to configured topics)
* agent service: supervisor, web UI, enrollment flow, and uploader
* local storage: persisted credentials under `/var/lib/insaion-agent/`
The agent prefers to run on the host (recommended) but can also be containerised as long as it has access to the necessary hardware resources and ROS2 system.
## Telemetry and host metrics
In addition to ROS2 topic telemetry and application metrics, the agent collects host-level metrics to help you monitor device health and performance. Typical host metrics include:
* CPU usage (per-core and aggregate)
* Memory usage and swap
* Network throughput and interface statistics
* Disk usage and I/O
* GPU utilization and memory (where available)
Host metrics are automatically collected and can be visualized on the Insaion monitoring dashboard right after registration.
To deploy a new agent, see [Installation](/agent/installation). After installation, use [Agent Operations](/agent/operations) to manage the service, update configuration, inspect logs, create support bundles, and troubleshoot the device.
## Security
* Enrollment uses enrollment keys. Rotate enrollment keys periodically.
* All outbound communication is over HTTPS with certificate validation by default.
* Agent runs with only the privileges it needs.
If you need an air-gapped deployment, contact your Insaion representative for an offline enrollment workflow.
# Create an alarm
Source: https://docs.insaion.com/alarms/create-alarm
Use the Create Alarm form to add a new rule that monitors your devices or data streams and notifies you when a condition is met. The form is designed to be approachable — fill in the human-friendly fields and the app will guide you through the important options.
### What you’ll see on the form
* Alarm Name: A short, descriptive name that helps you and your team understand what this rule monitors.
* Description: A longer, optional note describing the purpose of the alarm and suggested actions when it fires.
* Alarm Type: Choose Single Metric, Group Comparison, or Log Threshold. Log Threshold alarms evaluate matching log volume, unique attributes, or numeric measures.
### Build the query (what to watch)
The form asks for a few pieces to identify the data the alarm should watch:
* Topic Pattern: The stream or topic pattern the rule looks at (the app may suggest common patterns).
* Schema and Field: Select the data schema and the specific field you want to evaluate (for example "temperature").
* Tags (optional): Add tags to limit the scope further (useful when you have many data series under the same topic pattern).
Use the preview or summary shown on the form to confirm you're watching the right data.
### Filters (target specific devices)
If you don’t want the alarm to run for every device, add device metadata filters. These let you target only devices with certain properties — for example, a specific model, location, or customer.
* For Single Metric alarms: add a single metadata filter that all matched devices must satisfy.
* For Group Comparison alarms: define filters for Group A and Group B so the system can compare the two sets.
If you leave filters empty the rule applies to all devices matching the topic pattern.
### Condition (when should it fire)
Set the condition that will trigger the alarm:
* Evaluation Method: Choose whether the alarm looks at the latest single value or an aggregation (average, sum, min, max) across a time window.
* Evaluation Window: When using aggregated methods, set how long the system should look back (e.g., 5 minutes).
* Trigger Condition: Single Metric alarms support greater-than, less-than, exact equality, and inequality. Group Comparison also supports percentage comparisons.
* Threshold: The numeric value that will cause the alarm to trigger when the condition is met.
### Log threshold alarms
Log threshold alarms reuse the monitoring query builder, so the source, topic, field, tag filters, and text filters behave like log queries on the Monitoring page. Text filters support contains, does not contain, and regular expression matching.
Choose one compute mode:
* Count matching logs: Counts entries for the selected log field.
* Unique attribute values: Counts distinct values of the selected field or a tag written as `tag:key`.
* Numeric measure: Aggregates a numeric field with average, sum, minimum, maximum, median, p75, p90, p95, p98, or p99.
Log thresholds support greater-than, greater-than-or-equal, less-than, less-than-or-equal, exact equality, and inequality. Equality compares the computed numeric result exactly.
You can optionally group results by device, site, value, or one tag. Grouping still creates one alarm state and one incident: the alarm fires when any group breaches, and the incident includes a bounded list of breaching groups.
The maximum evaluation window is one hour. Count and unique modes treat no matching entries as zero, which makes a condition such as "less than 1" useful for detecting silence. A measure with no numeric values has no result unless missing-data notifications are enabled.
The preview runs the same monitoring query used for plotting. A preview failure does not prevent saving, but invalid filter, aggregation, or grouping combinations are rejected by the API.
### Notifications (third-party channels)
You can route alarm events to connected third-party channels directly from the alarm form.
* Channel selection: choose one or more connected channels (Slack, Telegram, or Microsoft Teams).
* Reuse destinations: channels are managed centrally in Settings and can be reused across multiple alarms.
* Resolve behavior: if a selected channel has notify-on-resolve enabled, it receives both firing and resolved messages.
If no channels are available, use the Manage channels shortcut in the form and configure them first in [Settings > Notifications](/settings/notifications).
### Settings
* Evaluate as soon as data arrives: When enabled, the alarm is checked within about a second of the data reaching the cloud, instead of waiting for the next scheduled check. Recommended for safety-critical conditions.
* Reaction Speed: Only shown when the above is enabled. The alarm is evaluated at most once per window however many devices are reporting, so a faster window reacts sooner and a slower one costs less on large fleets.
* Check Interval: How often the rule is evaluated (for example every 60 seconds). Shorter intervals give faster detection but may increase load. When "Evaluate as soon as data arrives" is on this becomes the Heartbeat Interval: a backstop check that still runs when no data arrives at all. It is what detects a missing-data condition and what resolves an incident after a device goes quiet, so it stays in effect either way.
* Enable toggle: Decide whether the alarm should be active immediately after saving.
### Save and cancel
Use the Save button to create the alarm. If a required field is missing the app will highlight it and prompt you to complete the form. Use Cancel to close the form without saving changes.
### Practical tips
* Name alarms clearly and include a description with recommended next steps (who to contact, where to check, etc.).
* Start with conservative thresholds and test a rule in a limited scope before enabling it fleet-wide.
* Use metadata filters to reduce noise and focus on meaningful groupings of devices.
***
# Incidents
Source: https://docs.insaion.com/alarms/incidents
## Incident History
The Incident History page gives you a clear, chronological view of incidents raised by your alarm rules. It’s designed to help you triage issues quickly, see which alarms are most active, and find the context you need to resolve problems.
### At-a-glance information
Each row in the incident list shows the most relevant details so you can quickly scan and prioritize:
* Status: The current lifecycle of the incident (Open, Acknowledged, Resolved). Color-coded badges make it easy to spot urgent items.
* Triggered: A human-friendly time indicator (e.g., "5 minutes ago") with the exact timestamp available on hover.
* Alarm Name: Which alarm rule created the incident, so you know what condition was met.
* Summary: A short description of why the incident fired to help you triage faster.
Click any row to see more details or use the action menu to analyze the incident with Insaion Copilot.
### Filters and time ranges
Use the controls above the list to narrow the incidents shown:
* Status filter: Show only Open, Acknowledged, or Resolved incidents.
* Alarm filter: Limit the list to incidents from a specific alarm rule.
* Time range picker: Focus on recent events or look back over a custom period.
There's also a Clear Filters button to quickly reset all filters.
### Sorting and pagination
You can sort the list by status, triggered time, or alarm name using the column headers. Results are paginated so you can step through large sets of incidents. Use the page controls at the bottom of the list to move between pages.
### Analysis
For a complete walkthrough of the AI flow, see [Copilot Incident Analysis](/copilot/incident-analysis).
Click the action menu (three-dot button) on an incident to access quick actions such as:
* Analyze with Copilot: Launch incident analysis with context preloaded so you can investigate root causes faster.
When you choose Analyze with Copilot, the app starts an AI-assisted investigation using the incident context and related telemetry.
During analysis, Copilot correlates relevant signals, suggests a focused visualization layout, and highlights likely causes or related anomalies to validate.
When additional packet-level evidence is required, Copilot prepares an MCAP extraction request with a scoped time window and pipelines. After approval, upload and artifact registration proceed automatically, and Copilot resumes deep analysis in the same thread.
Final findings are streamed live and stored as a structured report so they remain available after refresh or reconnect.
You can continue exploring the same incident manually in the embedded Lichtblick visualizer at any point.
If your workspace reaches its AI credit limit, the app will show a clear warning and you can continue with manual investigation using the same incident context.
### Best practices
* Triage Open incidents first — these indicate active conditions that may need immediate attention.
* Acknowledge incidents you’re investigating so teammates know someone is working on them.
* Resolve incidents after the problem is fixed to keep the list focused on ongoing issues.
### Troubleshooting tips
* If expected incidents do not appear, confirm the alarm rule is enabled and that the time range or status filters do not exclude the event.
* Use the alarm name to jump back to the rule definition if you need to adjust thresholds or scope.
# Alarms overview
Source: https://docs.insaion.com/alarms/overview
The Alarms page helps you keep track of important events and conditions across your monitored devices and data streams. It provides two main views: Incident History and Alarm Rules. Use this page to review recent incidents, manage alarm rules, and quickly see which alarms need attention.
Alarm rules can evaluate a single metric, compare two device groups, or evaluate logs by matching count, unique attribute count, or numeric measure.
### Tabs
* Incident History: A chronological list of incidents triggered by alarm rules. Use this view to investigate what happened, when, and which alarm triggered.
* Alarm Rules: A list of the configured alarm rules. From here you can create new alarms, edit existing ones, enable/disable them, or delete rules you no longer need.
### Key UI elements
* Create Alarm: Click the "Create Alarm" button to open the alarm form and add a new rule. The form walks you through naming the alarm, describing it, and defining the condition that triggers it.
* Tabs (Incident History / Alarm Rules): Switch between views using the tabs at the top. The app remembers your last selected tab so you can pick up where you left off.
* Filters: Use the filter controls to narrow down the list by name, status, enabled state, alarm ID, and time range (for incidents). Filters are reflected in the page URL so you can share or bookmark specific views.
### Alarm Rules view
In the Alarm Rules tab you will see a table of all alarm rules. Each row shows:
* State: Live health of the alarm (e.g., Firing, OK, Error).
* Alarm Name: The friendly name you gave the rule.
* Summary: A short, readable explanation of the rule condition so you can quickly understand what it watches.
* Enabled: A toggle to enable or pause the alarm without deleting it.
* Actions: Quick actions to edit or delete the rule.
Click a row to expand it and see more details, including a longer description, the device metadata filter (if any), evaluation interval, live state details, and the alarm ID which you can copy for reference.
Grouped log alarms use simple-alert behavior: groups add context to one rule and one incident rather than creating an incident for every device or attribute value.
### Incident History view
The Incident History tab lists incidents raised by alarm rules. For each incident you can typically see:
* When the incident occurred and when it was last checked.
* Which alarm rule triggered the incident.
* The current state of the incident (open, resolved, etc.).
* Context and details about why it fired so you can triage the issue quickly.
Use Analyze with Copilot from the incident actions to launch guided triage, MCAP extraction (when needed), and structured incident reporting. For the full workflow, see [Copilot Incident Analysis](/copilot/incident-analysis).
Use the time range filter to focus on recent activity or to look back over a specific period. This helps when investigating a specific outage or performance swing.
### Tips for effective use
* Give alarms clear, actionable names and include a description so team members know what to do when they see an incident.
* Use device metadata filters to target only relevant devices and reduce noise.
* When testing a new rule, consider leaving it disabled or setting a conservative threshold until you've validated it.
### Troubleshooting and next steps
* If an expected alarm does not appear in Incident History, check that the rule is enabled and that the condition matches the expected data path and values.
* Use the alarm ID (copyable from the expanded view) when discussing a rule with your team or support.
# Incident Analysis
Source: https://docs.insaion.com/copilot/incident-analysis
Use Insaion Copilot to investigate incidents with AI-assisted triage, MCAP extraction workflow, and structured reporting.
## Insaion Copilot Incident Analysis
Insaion Copilot provides guided incident triage directly from the incident drawer. It combines alarm context, reduced telemetry summaries, and packet-level analysis (when needed) into one continuous investigation flow.
## What Copilot does during incident analysis
When you launch analysis from an incident, Copilot can:
* Build a focused investigation context from incident metadata and alarm rule details.
* Correlate relevant logs, metrics, and signal changes around trigger time.
* Request an MCAP extraction window when baseline evidence is not conclusive.
* Continue automatically with deep packet-level analysis after MCAP artifacts are ready.
* Stream findings into the conversation and persist a structured report for later review.
Copilot output accelerates troubleshooting, but teams should always validate conclusions against raw data and domain knowledge.
## Start analysis from an incident
1. Open the Incidents page.
2. Select the incident to investigate.
3. Open the action menu.
4. Select Analyze with Copilot.
Copilot opens the incident analysis view with context preloaded and direct access to the embedded Lichtblick visualizer.
## End-to-end analysis flow
1. Copilot starts baseline triage on incident context and reduced telemetry.
2. If baseline evidence is conclusive, Copilot returns a root-cause summary immediately.
3. If baseline evidence is inconclusive, Copilot prepares an MCAP extraction request with a scoped time window and relevant pipelines.
4. After approval, the MCAP upload workflow runs and artifacts are registered.
5. Copilot resumes deep analysis automatically and streams report updates in real time.
6. The final report is stored in the thread and available on reconnect.
## Recommended operator workflow
1. Confirm incident timing, status, and affected entities.
2. Review Copilot summary and suggested related signals.
3. Validate key hypotheses in Lichtblick plots and related logs.
4. Approve MCAP extraction when requested and monitor upload status.
5. Review or export the generated incident report.
6. Acknowledge or resolve the incident based on validated findings.
## AI credits and limits
Copilot analysis consumes AI credits. If your organization reaches its limit:
* New AI-assisted analysis requests are paused.
* Manual analysis remains available with the same incident context.
For usage and limits, see the Billing page.
## Best practices
* Keep alarm names and descriptions specific to improve Copilot context quality.
* Add notes and labels during triage to preserve investigation history.
* Resolve incidents only after confirming the underlying condition is cleared.
# Add device
Source: https://docs.insaion.com/devices/add-device
Devices register with your Insaion workspace using an **enrollment key**: a long-lived secret that the agent presents when it first contacts the backend. You pick a key in the dashboard, copy the generated install command, and run it on the robot — the agent registers itself and appears on the Devices page.
Enrollment keys are created and managed under **Settings → Enrollment Keys**, and can be selected directly from the Add Device page, so you never need to keep your own copy of the secret.
## Add Device flow
Devices → **Add Device** opens a single page. Choose how to install the agent, then everything else is on the same page — the install command updates live as you change options.
### 1. Installation method
Choose where the agent will run:
* **Ubuntu / Debian**: native install as a `systemd` service.
* **Docker**: run as a container with the required host mounts and environment variables.
### 2. Enrollment key
Pick one of your existing enrollment keys from the dropdown, or create a new one without leaving the page. The selected key is hidden by default; use the eye icon to reveal it and the copy icon to put it on your clipboard.
If you keep your keys in a secrets manager, use **Paste a key manually** instead.
### 3. Agent configuration
Every option is off by default — switch on only what your robot needs:
* Custom ROS setup script (Ubuntu) or custom ROS workspace directory (Docker).
* Middleware (RMW): FastDDS, CycloneDDS, or Zenoh, each with its own settings.
* ROS domain ID, automatic discovery range, static peers, localhost-only mode.
* Docker only: the ROS 2 distribution used for the container image.
### 4. Install command
Copy the generated command and run it on the target machine. The enrollment key is masked on screen; copying always copies the real command.
### 5. Agent status
The page then watches for your device and reports when the agent is healthy:
* Agent installed and registered
* Agent connected to Insaion
* Agent version reported
* ROS topics discovered
Detection is scoped to the enrollment key you selected, so you only see the device that came from *your* command. When everything is green, jump straight to the device to configure it.
## Enrollment keys
Enrollment keys are persistent secrets managed under **Settings → Enrollment Keys**. They are designed for repeatable and bulk device registration — bootstrap scripts, golden images, container environments. Treat them like API keys: protect them, rotate them periodically, and name them so you can audit which batch of devices used which key.
Keys are stored encrypted, so you can reveal an existing key at any time from Settings → Enrollment Keys or from the Add Device page. Keys created before this behaviour existed are shown as *Created before keys could be shown* and can only be replaced with a new key.
**Steps**
1. In Devices → Add Device, select an existing enrollment key or create a new one.
2. Copy the generated install command.
Example:
```bash theme={null}
curl -fsSL https://get.insaion.com/setup.sh | sudo ENROLLMENT_KEY="your-enrollment-key-here" bash
```
3. Run the command on the target Linux machine.
4. The installer writes the enrollment key to `/etc/default/insaion-agent`, installs the `insaion-agent` systemd service, and starts it.
5. The agent uses the enrollment key to authenticate and register automatically. The device appears on the Devices page — and in the Agent status block on the Add Device page — shortly after.
## Troubleshooting
* Enrollment key rejected: verify you copied the key exactly and that the key is still active (not revoked or expired).
* Automated install not registering: confirm the `ENROLLMENT_KEY` is present in `/etc/default/insaion-agent` and that the device can reach the Insaion backend over the network.
* Agent status never turns green: verify the service is running with `sudo systemctl status insaion-agent` and that the device can reach the Insaion backend.
* Check agent logs for detailed error messages about enrollment or connectivity with `sudo journalctl -u insaion-agent -f`.
## Security and lifecycle
* Treat enrollment keys like secrets. Store them in a secrets manager or environment variables that are not checked into source control.
* Rotate keys periodically and revoke keys that are no longer needed. After revocation, devices that registered with a revoked key will continue to operate normally; revocation prevents new enrollments with that key.
* Use descriptive names when creating keys so you can identify which deployment or image used each key.
## Best practices
* Create one enrollment key per deployment, site, or image so you can tell which batch of devices used which key.
* Rotate keys periodically and revoke keys that are no longer needed.
* Limit distribution of keys, and revoke rather than share when a device leaves your control.
* Monitor and audit the Devices page and enrollment key usage regularly.
# Device configuration
Source: https://docs.insaion.com/devices/device-config
Deep dive into the Device Configuration page. Covers data collection (monitoring and recording), rolling buffer settings, templates, device metadata, and more.
## At a glance
The device Config tab has three sections in the left sidebar:
* **Overview** — device name, type, description and metadata.
* **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.
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 — there is no need to restart the agent or the device.
### 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.
### 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. They show a padlock and cannot be switched off.
* **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.
#### 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:
| State | Meaning |
| -------- | ------------------------------------------------------------ |
| Empty | Not recorded. |
| Check | Recorded because you ticked this topic. |
| Asterisk | Recorded because a **rule** matches it, such as `/camera/*`. |
| Cross | Matched by a rule but explicitly **excluded**. |
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 because 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 and number of recording sets.
* **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. Not applicable when the policy is `NONE`.
* **Uploads to** — the storage endpoint and bucket the agent writes to. Shown for reference; it is configured on the device itself.
* **Recording sets** — each set writes its own MCAP files with its own **split duration** (how long a single file may get before a new one starts). Keep the split small to limit file size and the amount of data at risk if a file is lost.
Most devices need only one recording set, and one is created for you the first time you tick a Record checkbox. Add more only when different topics need different file lengths. 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.
> **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.
## 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](/settings/templates) for creating and editing them.
## Metadata
The Metadata section on the Overview tab allows you to add custom key-value pairs to help identify and organize devices. Common metadata includes:
* Software versions
* Hardware serial numbers
* Firmware versions
* Hardware models
Metadata serves as tags for advanced filtering, grouping and to compare devices in dashboards and alerts. You can add, edit, or remove metadata entries at any time. Changes take effect immediately.
## Example use cases
* **Dashboards and alarms** — monitor `/battery_state` and `/cmd_vel`, and downsample a chatty `/odom` to 2 Hz.
* **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, and keep the split duration small.
* Use the `Unassigned` filter after onboarding a device to check nothing important was missed.
* 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.
* **A topic is ticked but no data arrives.** Confirm the schema type is supported for monitoring, and check the save actually completed.
* **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.
# Device details
Source: https://docs.insaion.com/devices/device-details
Deep dive into the Device Details page. Covers data sources, UI states, device metadata, and more.
## At a glance
When you open a device's details page you'll find:
* The device header with the device name, type (if any), Site (if any), a live status indicator (Online / Offline) and a description.
* Data Collection: sources discovered automatically from the device (host metrics and ROS 2 topics), and whether each is monitored, recorded or both.
* Device Metadata for easy identification and search.
## 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
The Config tab's **Data Collection** section lists every source the agent has discovered on the device and what the platform does with each one:
* **Host metrics**: CPU, memory, disk and network usage from the device's operating system. These are always collected once the agent is running.
* **ROS 2 topics**: discovered from the ROS graph, each one available to **Monitor** as live telemetry, to **Record** to the on-device rolling buffer, or both.
Tick the columns you want, then Save. The agent starts collecting within a few minutes and the data appears in dashboards — there is no need to restart the agent or the device.
For the full reference on the two columns, glob rules, downsampling and the rolling buffer, see [Device configuration](/devices/device-config).
## OpenTelemetry inventory and toggle
The Device Details page also includes an OpenTelemetry Inventory section.
* OTel ingestion is enabled by default.
* Use the OTel ingestion toggle to enable or disable OpenTelemetry collection for that device.
* The inventory lists discovered services and their emitted metrics, logs, and traces.
If no entries are shown yet, the device may not have emitted OTel data in the selected period.
To start sending data from your app, point your OpenTelemetry exporter to:
* Endpoint: [http://127.0.0.1:4317](http://127.0.0.1:4317)
* Protocol: OTLP/gRPC
For dashboard query setup with otel\_metrics, otel\_logs, and otel\_traces, see [OpenTelemetry in Monitoring](/monitoring/opentelemetry).
## Metadata
The Metadata section allows you to add custom key-value pairs to help identify and organize devices. Common metadata includes:
* Software versions
* Hardware serial numbers
* Firmware versions
* Hardware models
Metadata serves as tags for advanced filtering, grouping and to compare devices in dashboards and alerts. You can add, edit, or remove metadata entries at any time. Changes take effect immediately.
## Best practices
* Give devices meaningful names (ID + role, e.g. "AMR Sector 4B") so they are easy to find.
* Add a short description with installation notes (mounting location, contacts, or serial numbers).
* Complete the setup right after provisioning devices to avoid confusion in dashboards or alerts.
# Device recordings
Source: https://docs.insaion.com/devices/device-recordings
Learn how to view, manage, and upload device data recordings. Covers the timeline, recordings list, and upload/download features.
# Device Recordings
Easily browse, manage, and upload your device's recorded data. The Device Recordings page provides a visual timeline, a searchable and grouped recordings list, and powerful tools to help you get the most from your device's data.
## At a glance
When you open the **Recordings** tab for a device, you'll see:
* **Timeline:** An interactive, zoomable timeline showing all available recordings for the selected time range.
* **Recordings List:** A grouped table showing all recordings, with each recording expandable to reveal its individual segments.
* **Upload Progress:** Real-time feedback on ongoing uploads to the cloud.
## Timeline
The timeline gives you a visual overview of all recordings for your device. Each block represents a recording session:
* **Green:** Fully uploaded to the cloud.
* **Amber:** Available locally, not yet uploaded.
* **Gray:** Evicted (no longer available on device).
You can:
* **Zoom and pan** to explore different time periods.
* **Select a range** by dragging on the timeline to filter the recordings list below.
* **Click a block** for details and upload options.
> **Tip:** Use the calendar button to quickly jump to a specific date.
## Recordings List
Below the timeline, you'll find a grouped table listing all recordings in the selected range. Each recording can be expanded to show its individual segments. For each recording and segment, you can see:
* **Start/End Time**
* **Duration**
* **Pipelines** — the recording sets included, as configured in [Data Collection](/devices/device-config)
* **Size**
* **Cloud Status** (uploaded, uploading, queued, etc.)
### Segment Grouping
Recordings are now grouped by their recording ID. Expanding a recording reveals all its segments, each with its own details and actions. This makes it easier to manage large or long-running recordings that are split into multiple segments.
### Actions
* **Download per Segment:** Download any individual segment directly. If the device records more than one set, you can choose which pipeline to download for each segment.
* **Visualize in Viewer:** Instantly open any segment in the embedded Lichtblick visualizer for in-browser visualization and analysis. Click the "View" action on a segment to launch the viewer.
* **Delete:** Remove a recording or a specific segment from the cloud (irreversible).
* **Upload:** If a recording or segment is not yet uploaded, you can trigger an upload from the timeline or details popover.
## Upload Progress
Ongoing uploads are shown in a panel at the bottom corner. You can monitor progress and see when uploads complete.
## Best practices
* Regularly upload important recordings to the cloud to prevent data loss.
* Use metadata and naming conventions to keep recordings organized.
* Download recordings or segments for offline analysis or sharing as needed.
* Use the embedded Lichtblick visualizer to quickly inspect and validate your data before downloading.
## Troubleshooting
* If a recording is missing, check the selected time range and device status.
* For upload issues, ensure the device is online and has network access.
* Contact your administrator if problems persist.
# Devices overview
Source: https://docs.insaion.com/devices/overview
Manage your fleet: add and configure devices, view status, and drill into details.
## Devices list
The Devices page is the central place to monitor and manage every device that's connected to your system. A "device" is any physical or virtual unit (edge computer, sensor, robot, gateway, or embedded controller) that runs an agent and reports telemetry, status and logs back to the platform.
### What you'll see on this page
* A searchable, paginated table with one row per device. Each row shows the device's identity and key operational fields so you can quickly scan fleet health.
* Columns (default):
* **Name**: human-friendly device name.
* **Template**: the device template (if any) that defines default configuration for this device.
* **Type**: device type or model. (AMR, Drone,...)
* **Site**: the physical or logical site where the device is located.
* **Agent Version**: version of the agent running on the device.
* **Status**: online / offline with last seen timestamp.
* **Created At**: timestamp when the device was first registered.
### Filters and search
* Filter by Name, Type, Status and Site to narrow the list.
* Full-text search over device name, ID, and tags.
* Sort by Name, Site, or Created At for quick triage.
### Device registration and automatic appearance
Registered devices appear automatically in this list as soon as they finish their enrollment or start sending heartbeats. Registration works through an enrollment key: select an existing enrollment key (or create one) on the Add Device page, then run the generated install command so the systemd service registers automatically (See the [Agent installation](../agent/installation) page.).
See the [Add device](/devices/add-device) page for details.
When a device registers, it takes the default name based on the `Default Device Name Prefix` on Settings > Organization. If it is not set, the device name will be `device-xxxx` where `xxxx` is an increasing number. You can rename the device at any time in the device details view.
Welcome to Insaion’s documentation. Learn how to manage devices, monitor telemetry,
configure alarms, organize sites, and administer your organization.
## What is Insaion?
**Insaion is an AI-Driven Robotics Observability and Monitoring Platform.**
It is a unified platform designed to transform complex robot data into **clear, actionable insights**. Insaion empowers robotics teams to streamline development, optimize robot performance, and enhance operational efficiency with confidence.
### How Insaion Helps
Insaion provides the end-to-end visibility and intelligence needed to understand, improve, and operate complex robotic systems at scale:
* **Unified Data Observability:** Bring your entire operation into focus. Insaion unifies telemetry, logs, metrics, and events across your fleet and supporting infrastructure into a single, comprehensive pane of glass.
* **Full Native ROS2 Integration:** Built for the modern robotics stack, Insaion offers deep, native support for ROS2. Effortlessly map topics, types, and nodes without the overhead of custom bridges or complex translation layers.
* **AI-Powered Analysis:** Move beyond raw data. Our platform analyzes high-frequency streams to proactively detect anomalies and surface domain-specific insights, ensuring your team focuses on high-value problem solving.
* **Proactive Monitoring & Alerts:** Track robot health in real-time with granular precision. Configure intelligent alerts for critical events to resolve issues before they escalate, significantly reducing your Mean Time to Recovery (MTTR).
* **Effortless Data Ingestion:** Simplify your pipeline. Our intelligent, agent-based collection automatically gathers and consolidates the right data from diverse sources, providing an instant, 360-degree view of robot behavior.
## Getting Started
Start with the [Quickstart Guide](/quickstart) to create your workspace and connect your first device. For device registration details, see [Devices & Agents](/devices/overview) and [Agent Installation](/agent/installation).
# Logs
Source: https://docs.insaion.com/logs/overview
How to use the Log Management page to view, upload, filter, and manage recorded logs.
## Log Management
The Log Management page provides a simple, user-focused interface to view, upload and manage recorded log files. It is designed to help you find the logs you need quickly, see key details at a glance, and take common actions such as visualizing, downloading or deleting logs.
### What you can do on this page
* Upload log files manually: Use the "Manual Upload" button to select and upload a log file from your computer. Uploaded logs will appear in the table and can be interacted with like device-generated logs.
* Search and filter: Use the search box to find logs by name. Use the time-range control to narrow results to recent logs or a specific date/time window.
* Browse logs: The main table lists logs with useful columns so you can quickly scan for the entries you need.
* View details and edit metadata: Click any log row to open the details sidebar where you can view read-only information and edit the log's name, description and labels.
* Actions: Quickly visualize, download, or delete a log from the Actions column.
* Pagination: Move through pages of logs when you have many files.
### Page layout and controls
* Header: Shows the page title and a compact "Manual Upload" action for adding a log file from your computer.
* Filters area: Contains the search field and time-range picker. Clear filters with the "Clear Filters" button.
* Logs table: Each row in the table represents one log file. The columns include:
* Name — A human-friendly name for the log. You can edit this in the details sidebar.
* Source — Where the log came from, either the device name or "Manual Upload".
* Start Time — When the recording began.
* Duration — How long the recording lasted.
* Upload Date — When the file was uploaded to the system.
* Size — File size for quick assessment.
* Labels — Short tags that help you categorize logs. Click a label to edit it in the details sidebar.
* Actions — Quick buttons to visualize the log, download it, or delete it.
Rows are clickable — clicking a row opens the details sidebar for that log. Use the small expand icon at the start of each row to reveal a compact inline preview without opening the sidebar.
### Details sidebar
When you select a log, a details panel slides in from the right with both read-only information and editable metadata:
* Read-only information: ID, Start Time, Duration, Upload Date.
* Editable fields:
* Log Name — A required field. Friendly names make it easier to find logs later.
* Description — Optional notes about what the log contains.
* Labels — Short tags you can add, edit or remove. Labels help with filtering and organization.
Unsaved changes: If you try to close the sidebar with unsaved edits, you'll be prompted to either save your changes or discard them.
### Actions explained
* Visualize: Opens the log in the embedded Lichtblick visualizer so you can inspect topics and message streams.
* Download: Saves the original log file to your computer.
* Delete: Removes the log file from the system. You will be asked to confirm before deletion.
### Searching and filtering tips
* Use the search box for partial matches on the log name. The search is case-insensitive.
* The time-range picker supports quick relative ranges (e.g., last 24 hours) and custom start/end ranges.
* Combine search and time filters to quickly narrow results.
### Labels and organization
Labels are lightweight tags you can add to logs to organize them by project, test scenario, device, or any other category you find useful. Add multiple labels to a log, and use them together with the search and time filters to find what you need.
### Error and empty states
* If there are no logs to show, the page displays an empty state with a hint on how to upload or produce logs.
* If the app encounters a problem fetching logs, a clear error message is shown with guidance to retry or contact support.
### Common workflows
* Quickly find a recent log: Pick a short relative time range (e.g., last 24 hours) and sort the table by upload date.
* Tag logs for a test run: Select a log, open the details sidebar, and add labels that describe the test or scenario.
* Archive a log locally: Use the Download action to save a copy before deleting it from the system.
***
# Visualize logs
Source: https://docs.insaion.com/logs/visualize-logs
How to use the embedded Lichtblick visualizer to explore recorded logs without technical details.
## Visualize Logs
The Visualize action opens an embedded Lichtblick visualizer inside the app. It lets you inspect log contents visually, explore time-series data and message streams, add plots, mark intervals, and collaborate with Insaion Copilot in the same workflow.
### Main areas of the visualizer
* Left navigation: Choose the active workspace component (for example, the Topic Explorer or Chat). This quickly switches the main content area between exploring topics and conversing with Copilot.
* Center workspace: The area where plots and visual panels appear. Each panel (or "pane") can show one or more plots, and you can rearrange panes to match how you like to analyze data.
* Right-side timeline/controls: A compact timeline and playback controls that let you zoom and move through the recording period. Colored intervals (annotations) are shown on the timeline to highlight important sections.
* Top / side toolbars: Quick actions to add plots, save or load visualizer layouts, and change view options.
### Common workflows
* Quick inspection: Drag a topic's most important field into a pane and zoom the timeline to the period you care about.
* Compare signals: Add multiple fields to the same pane to see how they move together across time.
* Annotate and share: Mark an interval where a problem occurred, add a note, then share the session or save the visualizer layout for teammates.
* Use the chat for help: Ask the assistant to suggest plots or create a visualizer layout for common analysis tasks.
***
# OpenTelemetry in Monitoring
Source: https://docs.insaion.com/monitoring/opentelemetry
Enable OpenTelemetry ingestion from the UI and send OTLP data so it appears in dashboards.
OpenTelemetry is supported in Insaion Monitoring for metrics, logs, and traces.
This guide explains:
* Where to enable or disable OTel ingestion in the web app.
* Where your applications should send OTel data (endpoint and port).
* How to query OTel data in dashboards using otel\_metrics, otel\_logs, and otel\_traces.
* How traces appear in the UI even when you are focused on logs and timeseries panels.
## Before you start
To use OpenTelemetry with Insaion, make sure:
* The Insaion Agent is installed on the target device.
* The device is registered and visible in the Devices page.
* Your application runs on the same device (or can reach the device where the agent is running).
If the agent is not installed yet, follow [Agent Installation](/agent/installation).
## 1) Enable OpenTelemetry ingestion in the frontend
OpenTelemetry ingestion is enabled by default for new devices.
To check or change it:
1. Go to Devices.
2. Open the target device.
3. In Device Details, find the OpenTelemetry Inventory section.
4. Use the OTel ingestion toggle.
Behavior:
* Enabled: the agent accepts OTel OTLP/gRPC traffic and ingests it.
* Disabled: the agent stops ingesting OTel data for that device.
## 2) Send OTel data to the correct endpoint
By default, the agent listens for OTLP/gRPC on:
* Host: 127.0.0.1
* Port: 4317
* Endpoint: [http://127.0.0.1:4317](http://127.0.0.1:4317)
Use this endpoint in your OpenTelemetry SDK exporter settings.
Example environment variables for many SDKs:
```bash theme={null}
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
```
Notes:
* 127.0.0.1 means the exporter must run in the same network namespace as the agent listener.
* If your app runs in a separate container, point it to the host endpoint that reaches the device listener.
* If you send data but see nothing in dashboards, first verify the OTel ingestion toggle is on.
## 3) Query OTel data in the dashboard Query Builder
When configuring a panel query, the Query Builder includes OTel data sources.
You will see:
* otel\_metrics
* otel\_logs
* otel\_traces
Recommended usage:
* Use otel\_metrics for Timeseries, Stat, and Gauge panels.
* Use otel\_logs for Logs panels.
* Use otel\_traces when you want to explore traces available for the selected range and source.
## 4) Use the new Logs Query workflow
For Logs panels, use Log Text Search in the query builder.
Available match types:
* contains
* does not contain
* matches regex
Examples:
* contains: timeout
* does not contain: healthcheck
* matches regex: (?i)\b(error|critical|fatal)\b
Practical tip:
* Start with a broad contains filter, then tighten with regex if you need exact severity patterns.
## 5) Understand trace discovery in dashboards
Trace exploration is integrated into logs and timeseries workflows:
* In Logs panels, rows with a detected trace id show a Trace action.
* In expanded log details, trace\_id values are clickable.
* In Timeseries panels, trace exemplars can appear as markers.
* Clicking a trace marker or trace action opens the trace drawer.
Important:
* Trace drill-down is detection-driven. You usually discover traces from logs or metric exemplars, then open them.
* You may not always begin from a standalone trace search flow.
## Troubleshooting checklist
If data is missing:
* Confirm the device is online.
* Confirm OTel ingestion is enabled in Device Details.
* Confirm exporter endpoint is [http://127.0.0.1:4317](http://127.0.0.1:4317) and protocol is OTLP/gRPC.
* Confirm your selected dashboard time range includes recent events.
* Confirm your panel query data source matches the signal type (otel\_metrics, otel\_logs, or otel\_traces).
***
# Monitoring overview
Source: https://docs.insaion.com/monitoring/overview
This page gives a quick tour of the Monitoring Overview. It explains the key areas you will use to view and manage dashboards, panels, and live data. The goal is to help you find information fast and take common actions without diving into technical details.
## What you'll find on this page
* A list of dashboards you can open or create. Dashboards are collections of panels that display metrics and charts related to your devices and services.
* A flexible grid of panels where each panel shows a chart, gauge, or other visualization for one or more metrics.
* A time-range and refresh control so you can inspect historical data or watch live metrics.
* Controls to add, edit, rename, or delete dashboards and panels.
***
## Dashboard list and sidebar
On the left you will see the Dashboard sidebar. It lists all available dashboards and highlights the currently active one.
* Select a dashboard to open it in the main view.
* Use the Create button to add a new dashboard. You will be prompted for a name.
* Rename or delete dashboards using the actions next to each dashboard in the list.
* The last dashboard you visited is remembered for convenience.
***
## Header: quick controls
The top header gives quick access to the most common controls:
* Dashboard name — shows the name of the dashboard you're viewing.
* Sidebar toggle — show or hide the sidebar to give more room to the panels.
* Time range selector — choose an absolute or relative time window to view historical or live data.
* Refresh interval — set how often the page should pull new data in live mode.
* Add panel — create a new visualization panel on the current dashboard.
Tips:
* When you switch to a relative time range (for example, "Last 5 minutes"), the dashboard can auto-refresh to show live updates.
* Use the sidebar toggle when you need a larger canvas for many panels.
***
## Panel grid
The main area displays panels in a flexible grid. Each panel contains one visualization (chart, gauge, or stat) that shows metric data.
What you can do with panels:
* Resize and rearrange panels by dragging. Changes are saved to the dashboard layout so your arrangement persists.
* Maximize a panel to focus on a single visualization.
* Open a panel's configuration to change its title, metrics, visualization type, or queries.
* Remove a panel if you no longer need it on the dashboard.
Each panel also includes interactive features:
* Hover over charts to see exact values at a specific timestamp.
* Legends show device names or metric names for easy identification.
***
## Editing and configuring panels
When you open a panel's configuration you can:
* Change the panel title to something descriptive.
* Select the metrics or devices that the panel should show.
* Switch visualization types (for example, gauge, stat, or log).
* Save or cancel changes. If you navigate to a panel configuration directly via a link, use the cancel button to return to the dashboard.
The configuration page is designed for clarity: the left side shows settings and the right side usually includes a preview of the visualization.
### OpenTelemetry quick path
Insaion Monitoring supports OpenTelemetry metrics, logs, and traces.
* Enable or confirm ingestion from Devices -> Device Details -> OpenTelemetry Inventory (enabled by default).
* In panel Query Builder, choose OTel data sources (otel\_metrics, otel\_logs, otel\_traces).
* Use Logs and Timeseries panels to detect related traces and open the trace drawer directly.
For the full setup and query walkthrough, see [OpenTelemetry in Monitoring](/monitoring/opentelemetry).
***
## Time range and live mode
Use the time-range control to inspect a specific historical window (absolute) or to watch recent data (relative).
* Absolute time range: choose start and end times to examine a fixed interval of historical data.
* Relative time range: specify a duration (for example, last 15 minutes). When used with a non-zero refresh interval, the dashboard will poll for new data so charts update in near real-time.
If you enable live mode (a relative range with a refresh interval), the dashboard will periodically fetch new values and smoothly update the charts. Use this for monitoring ongoing activity or troubleshooting issues as they happen.
***
## Common user scenarios
* Troubleshooting a device: open the dashboard for the site or device, set the time window around when the issue started, and inspect panels for error counters, latency, or unexpected drops.
* Creating a focused view: create a new dashboard and add only the panels you care about for a specific incident or task.
* Sharing a view: copy the dashboard link to share with teammates; they will see the same layout and panels.
***
# Visualization types
Source: https://docs.insaion.com/monitoring/visualization-types
Overview of available visualization types for monitoring dashboards.
## Timeseries
What it shows
* A line chart plotting one or more numeric series over time.
When to use it
* Compare several devices, sensors, or metrics on the same time axis.
Interactions and info available
* Hover the chart to see exact values and timestamps in the tooltip.
* Zoom and pan the time range (use the dashboard time picker or, where available, drag to zoom).
* Toggle series visibility using the legend (if enabled) to focus on specific lines.
* When trace exemplars are present, markers are shown on the chart and can be clicked to open the related trace.
***
## Logs
What it shows
* A paginated or streaming view of log entries. Each row is a log event with timestamp and structured fields.
When to use it
* Investigate events, errors, or textual traces emitted by devices and services.
Interactions and info available
* Use Log Text Search in panel query settings with: contains, does not contain, or matches regex.
* Severity and level values are surfaced with stronger visual cues to make important lines stand out.
* Tag values are shown inline and in expandable detail rows for faster triage.
* If a trace id is detected in a row, use the Trace action to open that trace immediately.
* Click an entry to expand details and inspect related fields.
* Tail or stream live logs when the dashboard is in live mode.
***
## Trace drill-down
What it shows
* A trace waterfall and span details opened from related logs or metric exemplars.
When to use it
* Move from symptoms to root cause by jumping from a log line or timeseries marker into a full trace view.
Interactions and info available
* Open from Logs: click Trace on a row with a detected trace id.
* Open from Timeseries: click a trace exemplar marker.
* Review span hierarchy, timing, and service-level context in the trace drawer.
Tip:
* Trace discovery is context-driven. If you do not see traces immediately, narrow the time range around an incident and check related logs/metrics first.
***
## Gauge
What it shows
* A single-value radial gauge that highlights the current value relative to configured min/max and thresholds.
When to use it
* Monitor a single key indicator that needs to be visible at a glance, such as CPU usage, battery level, or temperature.
Interactions and info available
* Numeric value and optional progress visualization in the ring.
* Threshold colors indicate normal, warning, or critical ranges.
* Configure min/max, thresholds, units, and number of decimals in the panel settings.
***
## Stat
What it shows
* A large single numeric value, optionally with a small sparkline showing a recent mini-trend. Useful for dashboards that need to display many KPIs compactly.
When to use it
* Show totals, averages, counts, or the latest reading for a metric when space is limited.
Interactions and info available
* Optional sparkline to hint at the short-term trend.
* Click or configure to change how the value is aggregated (latest, average, sum, etc.).
***
## Image
What it shows
* An image pulled from a query (for example, a camera snapshot or an image stored as a metric). The panel shows the latest image for the selected time range.
When to use it
* Visual inspection tasks, camera feeds, or showing pictures associated with events.
Interactions and info available
* Configure which query supplies the image and the time range used to select the snapshot.
* If no image appears, verify the query is complete in the panel configuration.
***
## Host Map
What it shows
* A hexagonal (or grid) map of hosts/devices colored by a metric's value. Each tile represents a device or cluster, helping you spot hot/cold areas quickly.
When to use it
* Quickly identify groups of devices that are above or below thresholds (for example, many devices with high CPU or low battery in the same region).
Interactions and info available
* Hover tiles to see the device name and current value.
* Optional labels and cluster names can be toggled in the panel settings.
* Tile size and legend visibility are configurable.
***
## Map
What it shows
* Geographic or coordinate maps plotting positions from metrics (latitude/longitude) and optional labels. It can also render paths for moving devices.
When to use it
* Visualize locations and movement traces of devices, assets, or vehicles.
Interactions and info available
* Add at least two queries (latitude and longitude); an optional third query can provide labels.
* Pan, zoom, and inspect individual points. Paths can be rendered in the latest or full-mode depending on configuration.
***
## 3D Scene
What it shows
* A configurable 3D scene that renders robotics spatial data using shape-specific query slots (for example pose, vectors, status, or scalar height).
When to use it
* Use rich spatial context for robotics telemetry, including trajectories, direction vectors, status overlays, and occupancy-grid maps.
Interactions and info available
* Rotate, pan, and zoom the scene to inspect trajectories and points.
* Choose a shape type based on the data intent, then map query slots required by that shape.
* Tune scene options and shape properties from the same panel configuration flow.
* Add a static occupancy-grid map as a floor layer to align robot movement with environment layout.
### 3D panel refactor: shape-first workflow
The 3D panel now uses a shape-first setup designed for faster, clearer configuration.
* Shape picker: choose the rendering model first (Path Trail, Vector, Status Ring, or Bar).
* Slot-based query builder: each shape exposes required and optional data slots so you map telemetry fields to explicit semantics instead of wiring generic X/Y/Z only.
* Required-slot guidance: the editor highlights missing required slots before saving.
* Shape-aware defaults: new slots start with sane defaults for robotics telemetry (for example latest sample grouped by device).
### Query builder improvements for 3D
* Per-slot query cards: each slot has its own query editor with field hints.
* Rebinding on shape switch: if you change shape, existing queries are remapped so you keep most of your work.
* Optional fleet context: grouped-by-device queries naturally render one shape per device.
### Config options and scene controls
The Scene Options panel is split into focused controls:
* Shape properties: style, colors, labels, history depth, marker behavior, and other shape-specific options.
* Thresholds (shape-dependent): color transitions tied to metric levels.
* Coordinate frame: choose up-axis (Z-up for ROS or Y-up for graphics workflows).
* Grid and axes: toggle grid/axes and tune grid size and divisions.
* Viewport persistence: camera position can be retained as part of panel configuration.
### Static map layer (occupancy grid)
The 3D panel can render a static occupancy grid under your live shapes.
* Attach an existing static map, or capture one from an online device topic publishing `nav_msgs/msg/OccupancyGrid`.
* Adjust map opacity to balance readability between map and telemetry overlays.
* Use this mode for indoor navigation debugging, localization validation, and route verification.
***
## Tips for choosing the right visualization
* Use Timeseries for trends and multi-series comparison.
* Use Gauge or Stat for single high-priority KPIs that should be visible at a glance.
* Use Map or Host Map for spatial information and clustering.
* Use Logs when you need to inspect textual events instead of numeric metrics.
If you're unsure, start with a Timeseries or Stat panel and adjust to Gauge or Map once you know which single value or spatial relationship you need to highlight.
***
# Quickstart
Source: https://docs.insaion.com/quickstart
This guide helps you set up Insaion, invite your team, and connect your first device. If you only need the device agent steps, see the [Insaion Agent](/agent/installation) guide.
## 1) Create your account
1. Go to [https://app.insaion.com](https://app.insaion.com) and create an account.
2. Name your organization and workspace.
## 2) Add your first device
1. Go to Devices → Add Device.
2. Choose how to install the agent: Ubuntu (systemd) or Docker.
3. Select an existing enrollment key, or create a new one right there.
4. Switch on any ROS options you need — the install command below updates as you go.
## 3) Install the agent on the device
On the target Ubuntu device, run the install command from the Add Device page. The installer configures and starts the `insaion-agent` systemd service automatically. See the full steps in [Agent Installation](/agent/installation).
```bash theme={null}
curl -fsSL https://get.insaion.com/setup.sh | sudo ENROLLMENT_KEY="your-enrollment-key" bash
```
The device registers itself, and the Agent status block on the Add Device page turns green once the agent is connected and reporting.
## 4) Verify in the web app
* The device should appear online in Devices.
* Open the device detail to see status, metrics, and configuration.
* If you need to inspect the service locally, run `sudo systemctl status insaion-agent`.
## 5) Choose what the device collects
Open the device → Config → **Data Collection**. Each topic the agent discovered can be:
* **Monitored** — ingested as live telemetry for dashboards and alarms.
* **Recorded** — written to the on-device rolling buffer for incident playback.
Tick what you need and Save. See [Device configuration](/devices/device-config) for the full reference, or apply a [Template](/settings/templates) to reuse a setup across devices.
## 6) Explore core features
* Monitoring: check Logs and Dashboards to view telemetry.
* Alarms: create a new alarm and configure notifications.
* Templates & Sites: organize devices by site and reuse configurations.
* Team: invite members and set permissions for collaboration.
## Next steps
* Manage devices: [Devices & Agents](/devices/overview)
* Create alarms: [Alarms](/alarms/overview)
# Glossary
Source: https://docs.insaion.com/reference/glossary
Common terms used in Insaion.
* Device: a robot or machine running the agent.
* Agent: lightweight software that connects a device to Insaion.
* Site: a group of devices by location or project.
* Template: reusable data collection configuration — monitored topics and recording setup — applied to devices.
* Alarm: rule that detects conditions and notifies.
* Incident: a tracked occurrence of an alarm.
* Data Collection: the device configuration section where each topic is set to be monitored, recorded, or both.
* Monitor: ingest a topic as live telemetry, for dashboards, queries and alarms.
* Record: write a topic to MCAP files in the device's rolling buffer, for playback and upload.
* Rolling buffer: on-device storage holding recent MCAP recordings, trimmed automatically by a retention policy.
* Recording set: one group of recorded topics inside the rolling buffer, with its own file split duration. Called a pipeline in the agent configuration.
* Rule: a glob such as `/camera/*` that records every topic it matches, including ones that appear later.
* Downsampling: keeping only a fraction of a monitored topic's messages, either one in every N (stride) or at most N per second (max rate).
* Host metrics: CPU, memory, disk and network telemetry the agent always collects, published under `/host_metrics/`.
# Billing
Source: https://docs.insaion.com/settings/billing
How to read and manage your subscription, usage and invoices in the Billing & Plans page.
## Billing & Plans
This page helps you manage your subscription, review usage, and configure what happens when quotas are reached.
### At a glance
* Current plan and status: your active plan and subscription health (Active, Trial, Past Due, etc.).
* Billing period: start and end dates for your current cycle.
* Quick actions: change plan, open billing portal, add/update payment method.
Tip: If you are on a trial and haven't added a payment method, the page will show a clear banner with a button to add payment details so your service continues without interruption.
### Usage
The Usage section shows your data usage for the current cycle:
* **Live Ingestion (GB):** The amount of new data ingested this billing period. This is tracked monthly and resets each cycle.
* **Storage (GB):** The total amount of data you are currently storing on the platform.
* **AI Credits:** Shows the credits consumed in the current billing period against the allowance included with your plan. Each completed AI provider step consumes credits based on its raw input and output tokens.
**Device count is unlimited and does not affect your bill.** You are only billed for the amount of data you ingest and store, regardless of how many devices you connect.
What the progress bars mean
* The bar fills proportionally to usage. If usage goes beyond included quota, overage may apply (paid plans only, when overages are enabled).
* Values are updated periodically; check back if you see a sudden jump—some usage updates may take a moment to appear.
### Policies
Policies control what happens when limits are reached.
* Live Ingestion Policy
* Pause Data Collection: stop ingesting new live data when the monthly live-ingestion quota is reached.
* Allow Ingestion Overages: continue ingesting and bill overage usage (paid plans only).
* AI Credits Policy
* Pause When Credits Are Used: stop Copilot once current-period usage reaches the plan allowance.
* Allow Overages: continue processing and bill credits beyond the plan allowance (paid plans only).
* Free plan always uses hard limits for live ingestion and AI credits (no overages).
Choosing a policy
* Pause options are conservative and prevent extra charges.
* Allow overages keep your service uninterrupted but may result in additional charges.
If you switch to the Free plan, overage options are disabled automatically.
### How data billing works
Billing is based on data usage and AI credits:
* **Live ingestion (monthly):** Tracked as ingested GB within the billing month and reset each month.
* **Storage (current):** Tracked as total stored GB on the platform.
* **AI credits:** Added to current-period usage after each completed provider step based on raw input and output tokens. Once usage reaches the plan allowance, Copilot pauses unless AI credit overages are enabled.
You are **not** charged per device. For paid plans, overages are billed separately for each stream when applicable. For free plans, ingestion is blocked at quota and overages are not available.
### Next Invoice and Charges
The Next Invoice area shows the amount you will be charged at the next billing date. When available, you can open an invoice breakdown to see line items, discounts, taxes, and the due date.
* If the system is still calculating estimated usage, you may see a “calculating…” message for a short time.
* Click the invoice amount to expand a detailed breakdown of upcoming charges.
Tip: If you have scheduled changes to your subscription (for example, upgrading or downgrading on a future date), the page will show the scheduled plan and the effective date.
### Actions you can take
* Change Plan: opens the in-app flow to switch plans. Scheduled changes (if chosen) will be applied at the selected future date.
* Manage Subscription / Add payment details: opens the billing portal where you can update payment methods, view invoices, and manage subscriptions.
* Update Policies: from the page you can change how storage and live ingestion behave when you hit limits.
When to use each action
* Choose “Pause” policy if you want to avoid unexpected charges.
* Choose “Allow overages” if continuity of service is more important than avoiding extra billing.
### Status badges explained
* Active / Trial: subscription is active or in trial; if a trial doesn't have a payment method, the page will remind you to add one.
* Past Due / Unpaid: there may be an issue with your payment method—open the billing portal to update payment details.
* Cancelled: the subscription is cancelled or will not renew at the end of the period.
### Common questions
* Q: Why is the Allow Overages option disabled?
* A: The Free plan disables overages to prevent accidental billing. Upgrade to a paid plan to enable overages.
* Q: Do we overwrite old data when limits are reached?
* A: No. Overwrite-oldest behavior is no longer used.
* Q: I changed a policy but it doesn't look applied yet—what do I do?
* A: Policy changes are applied immediately, but some usage displays might take a minute to refresh. Try refreshing the page or wait a short while.
* Q: Where can I see past invoices?
* A: Use the Manage Subscription link to open the billing portal which contains your invoice history and payment receipts.
### Troubleshooting
* If your billing portal link doesn't open: check your internet connection and try again. If the problem persists, contact support with a screenshot of the error banner.
* If the usage shown looks incorrect: wait a few minutes and refresh—usage metrics are periodically updated. If numbers remain off, contact support and include the date range and the metric that looks wrong.
### Where to get help
If you still need assistance, open a support request from the app or contact your account manager. Include a screenshot of the page and the approximate time when you saw the issue to help us investigate faster.
### Quick tips
* Keep conservative pause policies enabled if you need strict spend control.
* Use the invoice breakdown to spot one-off charges or prorations when you change plans mid-period.
***
# Notifications
Source: https://docs.insaion.com/settings/notifications
Connect Slack, Telegram, and Microsoft Teams channels for alarm delivery and test them from the Insaion UI.
The Notifications page lets you connect third-party channels and route alarm events to the tools your team already uses. Channels are organization-level destinations and can be attached to one or more alarm rules.
## What you can do on this page
* Add channels for Slack, Telegram, and Microsoft Teams.
* Enable or disable channels without deleting them.
* Send test notifications to verify delivery.
* Edit channel names and notification behavior (such as resolve notifications).
* Remove channels no longer in use.
## Supported channel types
### Slack
* Slack uses an authorization flow from the UI (Connect Slack workspace).
* During authorization, Slack lets you choose the workspace and channel destination.
* Once connected, the channel is ready for alarm notifications.
### Telegram
* Telegram uses the official Insaion bot connection flow.
* In the Add Channel modal, create a Telegram channel, then connect by opening Telegram or scanning the generated QR code.
* The connection link is time-limited and must be completed before it expires.
### Microsoft Teams
* Teams uses an incoming webhook URL configured from your target channel workflow.
* Paste the webhook URL in the channel form.
* Use Send test to validate that Teams receives the message before saving.
## Channel settings
For each channel you can configure:
* Name: friendly label shown in alarm configuration.
* Enabled state: quickly pause notifications to that destination.
* Notify on resolve: send a message when incidents transition back to OK.
* Test delivery: send a test message from the channel row or modal.
## Attach channels to alarms
After channels are configured:
1. Open Alarms and create or edit a rule.
2. In the Notifications section, select one or more channels.
3. Save the alarm.
When the alarm fires, Insaion sends notifications to the selected channels. If notify-on-resolve is enabled, a follow-up message is sent when the incident resolves.
## Operational notes
* Channels are organization-scoped and reusable across alarms.
* Disabling a channel preserves its configuration but stops message delivery.
* Deleting a channel removes it from future deliveries; alarms that referenced it continue to run without that destination.
# Organization
Source: https://docs.insaion.com/settings/organization
Manage your organization settings.
## General
This page allows administrators to view and update the organization name and configure the default device name prefix used when new devices are registered.
### Organization name
* The organization name is the canonical name shown in the app headers and in generated communication.
Editing the Organization Name
* Click the edit icon next to the organization name to change it.
* Changes are saved immediately and will appear across the application where the organization name is displayed.
### Device name prefix (automatic numbering)
You can provide a default prefix that will be used when new devices are registered. This helps keep device names consistent and easy to identify.
* Example: If you set the prefix to `AMR`, devices will be named automatically as `AMR 1`, `AMR 2`, `AMR 3`, etc., in the order they are registered.
* If no prefix is set, the system will use the generic prefix `Device`, producing names like `Device 1`, `Device 2`, and so on.
* The numbering is incremental and applied automatically when a device is created. The system ensures uniqueness by incrementing the next available number for that prefix.
Behavior and edge cases
* Empty or whitespace-only prefixes are treated as "not set" and fall back to `Device`.
* Prefixes may include letters, numbers, and hyphens (`-`). Spaces are trimmed. Leading/trailing spaces will be removed.
* If you change the prefix later, existing device names are NOT renamed automatically. The new prefix will only apply to devices created after the change.
# Profile
Source: https://docs.insaion.com/settings/profile
Manage your user profile settings including name, email, avatar, password, and account preferences.
This page explains the Profile settings available to users. It covers the concepts, the most common tasks you can perform (update your name, email, avatar, password, and account preferences).
### What is the Profile page?
The Profile page is where you manage the personal information that identifies you in the system and control a few account-level preferences. Common sections you will see:
* Display name
* Primary email address (for notifications and recovery)
* Profile picture / avatar
* Password and security settings
Keeping this information accurate helps teammates find you, ensures notifications reach you, and improves overall account security.
***
### Edit your display name
1. Locate the Display name field on the Profile page.
2. Change the text and unfocus the field to save automatically.
Notes:
* Display name is what others will see across messages and lists. Use your full name for clarity.
### Change your email address
1. Enter the new email address in the Email field and click "Change" or "Save".
2. Check your new email for a verification link and click it to confirm.
Important:
* Until verification is complete, critical messages may still go to your previous address.
* If the new email is already associated with another account you'll see an error.
### Change your password
1. Click "Update Password" button
2. Enter your current password, choose a new password, and confirm it.
3. Click "Change password".
Security tips:
* Use a long passphrase or a password generator.
* If you suspect a breach, change your password immediately.
Error cases:
* Incorrect current password will prevent the change.
* New password may be rejected if it doesn't meet complexity rules.
***
## Troubleshooting & FAQs
* Didn't receive verification email: check spam, confirm address, and click "Resend verification" if available.
# Templates
Source: https://docs.insaion.com/settings/templates
Manage data collection templates for your devices, including creating, editing, deleting, and applying templates.
The Templates page manages reusable **data collection** presets. A template defines which topics your devices monitor as live telemetry and what they record to the rolling buffer, and applies that configuration to one or many devices at once. Use templates to speed up device onboarding and keep collection consistent across your fleet.
### What you'll find on this page
* A list of existing templates showing the name, description, how many topics it monitors, whether it manages recording, and the creation date.
* A clear indicator for the current default template (the one automatically applied to new devices).
* Quick actions to edit, delete, or apply a template to selected devices.
* Controls to create a new template from scratch or from an existing device configuration.
## What a template covers
A template carries both halves of a device's data collection:
* **Monitored topics** — with their downsampling settings.
* **Recording configuration** — the rolling buffer's policy, quota, recording sets and their topics and rules.
A template manages recording **only when it captures at least one topic or rule**. If you leave the Record column empty, the template covers monitoring only, and applying it leaves each device's rolling buffer exactly as it is. This is also why templates created before recording support existed never disturb a device's recording setup.
Host metrics are always collected, so they do not need to be part of a template. They are added automatically on every apply.
## Creating a new template
1. Click **Create Template**.
2. Give the template a descriptive name and, optionally, a description so other team members know what it is for.
3. Optionally toggle **Set as default template** to apply it automatically to all newly registered devices.
4. Tick the topics to collect. The editor is the same table as the device Data Collection view: a **Monitor** column, a **Record** column, namespace groups, glob rules and the rolling buffer settings. See [Device configuration](/devices/device-config) for how the columns and rules behave.
5. Click **Create Template** to save.
Notes:
* The topic list is built from everything the devices in your organisation have published, so connect a device before building a template.
* A template needs at least one monitored topic or one recorded topic to be saved.
* Names should be unique and descriptive (for example, "AMR Base Model").
* If you mark a template as default, it is used for every new device registered after that change.
## Editing a template
1. Find the template in the list and click **Edit**.
2. Update the name, description, default flag, monitored topics, or recording configuration.
3. Save your changes with **Update Template**.
The full template is always fetched before the editor opens, so you never edit a partially loaded configuration.
Editing propagates automatically to every device linked to the template that has **Auto-update** switched on, for both the monitoring and the recording halves. Devices with Auto-update off keep their current configuration until the template is applied to them again.
## Deleting a template
1. Click **Delete** on the template you want to remove.
2. Confirm the deletion in the confirmation dialog.
Warning: Deleting a template does not remove configuration already applied to devices. It only removes the saved template from this page. Devices linked to it keep collecting exactly what they were collecting.
## Applying a template to devices
From a single device:
1. Open the device's Config tab → **Data Collection**.
2. Click **Assign Template**.
3. Pick a template. Each row previews what applying it would do — how many topics it monitors, how many it records, or `recording untouched` when it does not manage recording.
4. Click **Apply template**.
From the Devices page, to configure several devices at once:
1. Select the devices you want to configure.
2. Open the group menu and choose **Assign Template**.
3. Apply the template you want.
Applying a template **replaces** the device's monitored topics, and its rolling buffer configuration when the template manages recording. The device then stays linked to the template until you detach it — see the template bar in [Device configuration](/devices/device-config).
Two things are adjusted automatically on apply:
* Host metrics are added, whatever the template contains.
* Message types that cannot be ingested as telemetry (`sensor_msgs/msg/Image`, `PointCloud2`, `OccupancyGrid`, and similar) are skipped in the Monitor half. They are still recorded if the template records them.
## Create a template from a device's configuration
If a device is already configured the way you want:
1. Click **From Device**.
2. Choose the device whose configuration you want to save.
3. Enter a name and optional description.
4. Optionally set it as the default template and save.
This copies the device's whole data collection — monitored topics with their downsampling, plus the rolling buffer configuration — into a new template.
You can do the same from the device itself with **Export Template** on the Data Collection view, which previews what will be captured first.
## Default template behavior
* The default template is applied automatically to new devices when they register.
* Only one template is default at a time. Setting a new default replaces the previous one.
* Existing devices are not changed when you change the default. Use Apply to update already-registered devices.
## Tips and best practices
* Use clear, consistent naming (include device type and purpose).
* Keep templates focused and reusable — a base template for common telemetry, specialised ones for particular sensor loads.
* Prefer glob rules such as `/camera/*` in the Record column over long lists of individual topics. A rule keeps working when a robot gains a new topic in that namespace.
* Use **From Device** or **Export Template** to capture a working configuration, then refine it.
## FAQ
* Can I preview what will change on a device before applying a template?
Yes. The Assign Template dialog shows, per template, how many topics it monitors and records before you apply it. For a full row-by-row review, apply it to a test device first.
* What happens to device data when I apply a new template?
Applying a template updates what a device monitors and records from that point on. Historical data is not deleted, but future collection follows the new rules.
* Does a template without recording turn recording off on my devices?
No. A template only manages recording when it captures at least one topic or rule. Otherwise each device keeps its own rolling buffer settings.
* Why is a topic I selected missing from the saved template?
Template topics are matched to the schema of a topic some device has published. If no device is publishing it any more, its schema is unknown and it cannot be stored as a template row — the page warns you when this happens. Use a glob rule for the Record half instead.
***
# User management
Source: https://docs.insaion.com/settings/user-management
Manage organization members, invite new users, change roles, and revoke invitations.
## Overview
The User Management page lets you see and manage everyone who has access to your organization. From here you can:
* View a list of current members and their roles.
* Invite new people to join the organization.
* See and manage pending invitations.
* Change the role of one or many members.
* Remove members from the organization.
This page is designed for organization owners and admins to keep membership up-to-date and to control access.
## Members
The Members tab shows all users who currently belong to your organization. For each member you can see their name, email, and role.
* Select one or more members using the checkboxes to perform bulk actions (change role or remove).
* Use the Actions menu on each row to change a single member's role or remove them.
What you can do:
* Quick look at roles — the Role column shows the role assigned to each user (for example: Owner, Admin, Member).
* Bulk selection — check the top-left checkbox to select all visible members and then use the bulk actions menu to change roles or remove users in one go.
When removing a member, you'll see a confirmation dialog asking you to confirm the action. This helps prevent accidental removals.
## Pending Invites
The Pending Invites tab lists all invitations you've sent but that haven't been accepted yet.
* Each invite shows the recipient email, the role they were invited to, when the invite was sent, and its current status (for example: pending or expired).
* Use the Actions menu next to an invite to resend it or revoke it.
Common scenarios:
* Resend an invite if the invited person didn't receive the email or needs a fresh reminder.
* Revoke an invite if it was sent to the wrong address or is no longer needed.
## Invite a New Member
Click the "Invite Member" button to open the invite dialog. You will be asked for the new person's email and the role you'd like them to have.
* Enter a valid email address and choose a role from the Role dropdown.
* Press "Send Invite" to send an invitation email. The new invite will appear under Pending Invites until the recipient accepts it.
Tips:
* By default a common role (for example "Member") will be selected to make inviting faster.
* If you make a mistake while entering the email, simply cancel and try again; no invite is sent until you press "Send Invite".
## Change Role
You can change a member's role at any time. Open the Actions menu for a user and select "Change Role" to pick a new role.
* You can change the role for a single user or use the top checkboxes to select multiple users and change roles in bulk.
* After changing roles, affected users will see the permissions and access associated with their new role the next time they use the app.
Guidance:
* Think about the permissions you want someone to have before changing their role.
* Bulk role changes are useful when reorganizing teams or updating access levels for a group of people.
## Remove Members
To remove a user, select them and choose the Remove action (either from the row Actions menu or from the bulk actions menu).
* A confirmation dialog will appear to make sure you want to remove the selected member(s).
* Once removed, the user will immediately lose access to your organization.
## Accessibility & Safety
* Important actions like removing a member or revoking an invite require confirmation so changes aren't made accidentally.
* If you need help with membership or invites, contact your organization owner or the support team.
## FAQ
* Q: What if an invited user doesn't receive the email?
* A: Try resending the invite from the Pending Invites tab. Also ask the recipient to check spam/junk folders.
* Q: Can I change a role back after I update it?
* A: Yes — just open the Change Role dialog again and pick a different role.
***
# Assign devices
Source: https://docs.insaion.com/sites/assign-devices
How to assign, move and remove devices from a site — step-by-step user guide with tips and screenshots.
## Assign devices to a site
This page explains how to assign devices to a site. It focuses on the day-to-day tasks you (as an operator or administrator) will perform when linking devices to an existing site. If you need to learn what a site is or how to create one, see the [Sites overview](./overview) and [Create a site](./create-site) pages.
What you'll learn on this page:
* How device-site assignment works conceptually
* Single-device assignment and removal
* Bulk assign and bulk unassign workflows
* Permission considerations and common edge cases
* Best practices and troubleshooting tips
***
### How assignment works
A site is a logical grouping used to organize devices by location, function or ownership. Assigning a device to a site updates the device's metadata so it appears within the site's device list and inherits site-level configuration, monitoring and access policies where applicable.
Key points:
* Assignment changes only the device's site reference — it does not modify device firmware, network settings, or remove any device-specific data.
* A device may only be assigned to one site at a time.
* Site-level alerts, dashboards, and reporting typically surface devices assigned to that site.
***
### Assign a single device to a site
1. Open the Devices view in the main navigation.
2. Locate the device you want to assign. Use the search box to filter by name, type, or status.
3. Click the three-dots menu on the device row and select "Assign to site".
4. In the site picker, select the target site from the dropdown or type to search.
5. Click Save or Confirm.
Expected result: the device details now show the new site, and the site device list will include the device within a few seconds.
***
### Move a device from one site to another
If a device is already assigned to Site A and you want to move it to Site B, follow the same steps above. The site picker will usually indicate the current site. When you save, the device is removed from Site A's device list and added to Site B's list.
Important: check for site-specific configurations.
***
### Bulk assign devices to a site
Use bulk assignment to save time when you need to assign tens or hundreds of devices to the same site.
Steps:
1. Open the Devices view and use filters to narrow the device list (for example by model, or status).
2. Use the checkbox in the table header to select devices on the current page. You can also use the row checkboxes to selectively pick devices.
3. If your UI supports it, click "Select all X results" to include devices across multiple pages.
4. Click the Bulk actions menu and choose "Assign to site".
5. In the dialog, pick the destination site and confirm.
Behavior and safety:
* The system should show a confirmation modal summarizing the action (e.g., "Assign 124 devices to Site Acme HQ?").
* Devices already assigned to other sites will usually be moved.
***
### Bulk unassign (remove devices from a site)
To remove devices from a site (set their site to "Unassigned"):
1. Go to the Devices page.
2. Select the devices you want to unassign.
3. Choose Bulk actions → Unassign from site. Confirm the action in the modal.
Behavior:
* Unassigning sets the device's site reference to empty; the device will no longer appear in site-specific dashboards or alerts.
* If you need to reassign the device later, follow the assign flows above.
***
### Best practices
* When moving devices between sites, perform a small test (2-5 devices) first to verify there are no unexpected side-effects.
* Use descriptive site names and keep a clean site hierarchy to avoid mistakes during assignment.
***
# Create a Site
Source: https://docs.insaion.com/sites/create-site
Step-by-step guide to creating a Site in Insaion, including UI, field validation, and best practices.
### Step-by-step (UI)
1. Open the Sites page (main menu → Sites).
2. Click "Create New Site".
3. Enter values for the form fields.
4. Review the form for validation warnings (see Field validation below).
5. Click Save — you should see a success notification and be returned to the Sites list.
### After create: quick next steps
* Add devices: create or onboard devices and set their `site` to the newly created site.
* Deploy agents: install and configure agents to connect devices at the site.
* Create monitoring rules: set up alarms for key metrics on devices at the site.
### Troubleshooting
* Q: I submitted the form but no site appears in the list.
A: Confirm you received a UI success notification. Refresh the list and check filters.
* Q: The site appears but I can't add devices.
A: Ensure your user role has permission to modify the site (Admin or Operator).
# Sites overview
Source: https://docs.insaion.com/sites/overview
Overview of Sites in Insaion — concepts, common workflows, and best practices for managing physical locations, devices, and monitoring.
## Sites — at a glance
Sites are the logical representation of a physical place where you deploy and monitor devices. A Site groups devices, templates, monitoring rules, agents, and configuration so you can manage and understand a location as a single unit.
This page explains the core concepts, typical user workflows, and practical tips for getting the most out of Sites.
## Key concepts
* Site: A container for devices and settings that correspond to a physical or organizational location (for example: a factory floor, building, or vehicle).
* Device: Any asset that connects to the platform (PLC, gateway, sensor, controller). Devices are assigned to a Site so telemetry and rules are scoped correctly.
* Agent: The software component that runs near or on devices to collect telemetry and forward it to the platform. Agents are often deployed per Site or per gateway.
* Monitoring Rule / Alarm: Conditions and thresholds applied to device telemetry. Rules are typically created at site level to trigger alerts and notifications.
* Role & Permission: Access controls that determine who can view or modify a Site and its resources.
## Typical Site workflows
The following common workflows show how Sites are used day-to-day.
### 1) Create a Site
Purpose: Register a new physical location in the platform.
Why: Sites give you the scope for searching, grouping, and applying monitoring consistently.
Example: Create a Site for "Plant 3 - Paint Line".
### 2) Add devices to a Site
Purpose: Associate physical devices with the Site so their telemetry appears in the correct context.
Tips:
* Use meaningful device IDs—include site or line prefixes if you expect many devices.
* If many devices are similar, assign a template to reduce repetitive configuration.
### 3) Deploy agents for the Site
Purpose: Ensure telemetry from devices at the Site is collected reliably.
Best practice: Pin the agent configuration in version control or deployment tooling, and use templated config files so you can redeploy quickly across multiple sites.
### 4) Use site dashboards and reports
Purpose: Provide operators and managers an at-a-glance view of site health.
What to include:
* Key KPIs (uptime, throughput, error rate)
* Device health and connection status
* Active alarms and recent events
* Topology map or floorplan links (if available)
Pro tip: Create a site-level dashboard that aggregates important metrics from device dashboards so operators don't need to open many pages.
## Example: Quick start (create-onboard-monitor)
1. Create a Site called "Warehouse A".
2. Onboard a device and assign it to "Warehouse A".
3. Install the agent on the device and configure the site ID.
4. Create a monitoring rule: if average temperature over 5 minutes > 30°C, create Alarm "High temp - Warehouse A" and notify me.
## Permissions and access control
Sites are often visible to many users but editable by a smaller set. Use roles to control access:
* Viewer: Can see assigned site dashboards and view device telemetry.
* Operator: Can acknowledge alarms and run troubleshooting steps.
* Admin: Can add/remove devices, change site settings, and deploy agents.
Best practice: Use least privilege. Give Operators the ability to interact with alarms and dashboards but keep critical configuration (templates, site deletion) limited to Admins.
## Best practices
* Standardize site naming: pick a convention (plant-line-room) and document it.
* Use templates for device consistency: reduces onboarding time and configuration drift.
* Monitor agent health separately: agent disconnection often explains missing telemetry.
## FAQs
* Q: Can a device belong to multiple Sites?
A: No — a device has a single canonical Site assignment. If a device moves, update its Site.
* Q: How do I move devices between Sites?
A: Edit the device's Site assignment in the device details page.