> ## Documentation Index > Fetch the complete documentation index at: https://docs.insaion.com/llms.txt > Use this file to discover all available pages before exploring further. # Tags > Describe your devices with key:value tags, keep their history, and use them to filter the fleet, dashboards, alarms and recordings. Tags are `key:value` pairs that describe a device, such as `customer:acme`, `software_version:1.4.2` or `env:production`. You set some of them yourself, and the agent reports others on its own. Every tag keeps its history, so Insaion knows which value a device had at any moment. The same tags, and the same way of writing filters, work across the app: * **Devices**: search the fleet, count devices per value, show tags as columns and edit tags on many devices at once. * **Dashboards**: filter every panel by tag, add a picker per tag, group charts by tag and mark when a tag changed. * **Compare panel**: put two tag values, or two periods, side by side. See [Compare panel](https://docs.insaion.com/monitoring/compare-panel.md). * **Alarms**: choose which devices an alarm watches, and put tags in notification messages. * **Incidents**: see the tags a device had when an incident opened, and what changed in the 24 hours before. * **Recordings**: find recordings by the tags their device had when they were recorded. * **Copilot**: incident analysis receives the device's tags and recent tag changes. ![Device Tags](https://mintcdn.com/insaion/VXH-ojP4YQTVK3OB/assets/devices/device-tags.png?fit=max\&auto=format\&n=VXH-ojP4YQTVK3OB\&q=85\&s=4ff497656b10e1e39948ef02f4cc26a1) ## Kinds of tags | Kind | Who sets it | Examples | Can you edit it? | | - | - | - | - | | Manual | People in your organization | `customer:acme`, `software_version:1.4.2`, `env:staging` | Yes | | Detected | The agent, from the device itself | `os.name`, `ros.distro`, `agent.version` | No, they update when the device changes | | Built-in | Device settings | `site`, `name`, `type`, `status`, `update` | Change them in the device settings or by assigning a site | ### Detected tags The agent reports facts about the device each time it connects. You can filter, group and compare on them like any other tag, but you can't change them by hand. | Key | Meaning | | - | - | | `agent.version` | Version of the Insaion agent | | `agent.install` | How the agent was installed: `systemd` or `docker` | | `os.name`, `os.version` | Operating system | | `kernel` | Kernel version | | `host.name` | Hostname | | `host.memory_gb` | Installed memory | | `cpu.model`, `cpu.arch`, `cpu.cores` | Processor | | `gpu.model`, `gpu.driver` | Graphics card, when present | | `ros.distro`, `ros.rmw`, `ros.domain_id` | ROS 2 distribution, middleware and domain | | `docker.version` | Docker version, when present | Keys starting with `os.`, `host.`, `kernel`, `ros.`, `agent.`, `container.`, `gpu.`, `cpu.` or `docker.` are reserved for the agent. ### Built-in keys Built-in keys come from the device record rather than from tags, but you write them in filters the same way: * `site`: the site the device is assigned to. `-has:site` finds unassigned devices. * `name`: the device name. * `type`: the device type, such as AMR or Drone. * `status`: `online`, `offline` or `pending-setup` (Devices page only). * `update`: `needs-update`, `up-to-date` or `unknown-version`, the agent update state (Devices page only). ### Naming rules * Keys use lowercase letters, digits and `_ . / -`, start with a letter, and are at most 63 characters long. * Values can be up to 200 characters. Matching ignores case. * Each device has at most one value per key at a time. Setting a new value ends the old one. ## Tags on a device Open a device to see its tags at the top of the page, grouped into your own tags and the ones the agent detected. Click the arrow to show all of them. ### Add a tag 1. Click **+ Tag**. 2. Type a key and a value. Existing keys and values are suggested as you type. 3. Choose when the tag applies from: * **Now**. * **Device registration**, to say the device has always had this value. * **A date**, to record a change that happened earlier, such as a software update rolled out last Tuesday. 4. Click **Save**. Backdating a tag rewrites the history from that moment on, so dashboards, comparisons and recording searches treat the device as having had that value since then. ![Add tag dialog](https://mintcdn.com/insaion/VXH-ojP4YQTVK3OB/assets/devices/device-add-tag.png?fit=max\&auto=format\&n=VXH-ojP4YQTVK3OB\&q=85\&s=531c1cc52c889831e37f276804d637d7) ### History, change and remove Click any tag to open its history: every value the key has had, when it started and ended, and who set it. From there: * **Change value** sets a new value, from now or from a date you choose (**Changed at**). * **Remove** ends the tag now. The history keeps the values it had. Detected tags show their history too, but have no Change or Remove buttons. ![Tag history dialog](https://mintcdn.com/insaion/VXH-ojP4YQTVK3OB/assets/devices/tag-history.png?fit=max\&auto=format\&n=VXH-ojP4YQTVK3OB\&q=85\&s=69c1d53f7072f74f28d2f608fd629ded) ## Tags on the Devices page The [Devices](https://docs.insaion.com/devices/overview.md) page uses tags to find and organize the fleet. * **Search bar**: type plain words to search device names, and conditions such as `site:barcelona ros.distro:jazzy -customer:internal` to filter. Press space or Enter to turn a condition into a chip. Click **Syntax** for a cheat sheet. * **Facets**: the sidebar lists status, site, type, agent update and every tag key, with the number of devices per value. Click a value to add it to the search, and click it again to remove it. The counts update as you filter. * **Columns**: use the column toggle next to a key in the sidebar to show that tag as a table column. * **Edit tags on many devices**: select devices with the checkboxes, then choose **Edit Tags** from the bulk actions menu. Choose **Set a tag** or **Remove a tag**, and when the change applies: now or a date. ![Devices page with tag search and facets](https://mintcdn.com/insaion/VXH-ojP4YQTVK3OB/assets/devices/device-tag-search.png?fit=max\&auto=format\&n=VXH-ojP4YQTVK3OB\&q=85\&s=fbc2698c297517831ce4d64d2ffaaa9d) ## Filter language Every tag filter in the app (Devices search, dashboard filters, panel **Where**, alarm scope, Compare scope and Recordings search) accepts the same syntax. | Write | Meaning | | - | - | | `customer:acme` | equals | | `-customer:acme` | does not equal, also true when the tag is missing | | `version:(1.4.1 OR 1.4.2)` | any of these values | | `version:1.4.*` | wildcard | | `host:~^amr-0[1-5]$` | regular expression | | `-msg:~debug` | does not match the expression | | `has:owner` | the tag is set | | `-has:owner` | the tag is not set | | `(severity:ERROR OR name:amr-07)` | any of several conditions, on any keys | | `customer:"acme corp"` | quote values that contain spaces | | `amr-07` | plain words search names, where the field allows it | A space between conditions means AND. Matching ignores case. ### Device tags and data tags Panel queries can filter on two kinds of tags: * **Device tags** are the tags on this page. In dashboards, Compare and Recordings they apply as they were when the data was recorded, so a robot upgraded on Tuesday counts as `1.4.1` before Tuesday and `1.4.2` after. On the Devices page and in an alarm's device list, they match current values. * **Data tags** belong to each data point, such as `cpu:cpu-total` on a CPU metric or `severity:ERROR` on a log. They filter the points of one metric, not which devices are included. ## Where tags are used ### Dashboards * **Dashboard filters** above the panels apply to every panel on the dashboard. Click **+ Variable** to add a picker for one tag key, so viewers can switch between values without editing panels. * **Where** in a panel's query keeps only data from devices, or points, with those tags. You can refer to a dashboard variable, for example `software_version:$software_version`. * **Group by** in a panel's query accepts any device tag, so a chart can draw one line per customer or per software version. * **Tag change markers**: turn on **Show Tag Changes** under **Markers** in a Timeseries panel to mark when a tag such as `software_version` changed on the devices in the panel. By default this covers your own tags plus `agent.version`. * **Device dashboards** show the device name and its tags in the header. See [Monitoring overview](https://docs.insaion.com/monitoring/overview.md#dashboard-filters-and-variables) for details. ### Alarms and incidents * An alarm's **Where** decides which devices it watches, with a live count of how many devices match now. See [Create an alarm](https://docs.insaion.com/alarms/create-alarm.md#scope-which-devices-to-watch). * Notification messages can include `{{tags.}}` and `{{tags.changes_24h}}`. * Each incident keeps the tags its devices had when it opened, and the tag changes from the 24 hours before. See [Incidents](https://docs.insaion.com/alarms/incidents.md#tags-and-recent-changes). ### Recordings The [Recordings](https://docs.insaion.com/recordings/overview.md) page has one search bar with the same syntax. Robot recordings match the tags their device had when each recording started. Manually uploaded files match their own tags and the device tags saved with them. You can add `key:value` tags to a manual upload in its details panel, for example `scenario:docking`. ### Copilot When Copilot analyzes an incident, it receives the device's tags and the tag changes from the 24 hours before, so it can point out that a problem started right after a software update. ## Best practices * Agree on a small set of keys across the team, such as `customer`, `software_version`, `env` and `hardware_rev`, and reuse them. * Set `software_version` (or your own release key) every time you roll out an update, with the real rollout time. It is what makes before and after comparisons and tag change markers useful. * Use **A date** when you record a change after the fact, so the history matches what happened on the robot. * Prefer tags over device names for grouping. Names change; tags carry history. If something's unclear or you hit a blocker, contact us on [Discord](https://discord.gg/ZJMPfMmu3S) or [[contact@insaion.com](mailto:contact@insaion.com)](mailto:contact@insaion.com) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.