> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Tags
> Organize and filter DevHelm resources with tags for grouping, routing, and reporting
Tags are coloured labels you attach to monitors. They are the workhorse primitive for filtering dashboards, routing alerts, and slicing reports without inventing rigid hierarchies.
**Tags vs environments vs resource groups.** Tags are *attributes* (e.g. `team=payments`). [Environments](/platform/environments) are deployment *stages* with variable substitution. [Resource groups](/platform/resource-groups) are membership *sets* with composite health. Use whichever matches the question you're answering.
## Model
| Property | Notes |
| -------------------- | --------------------------------------------------------------------------------------------------------------- |
| **`id`** | UUID identifier. Tags are referenced by name in YAML and CLI flags but by UUID in REST responses. |
| **`name`** | Unique within the organization. Conventionally lowercase, hyphenated (`payments`, `customer-facing`, `tier-1`). |
| **`color`** | Hex code (e.g. `#10b981`). Used for visual grouping in lists and incident timelines. |
| **`organizationId`** | Organization the tag belongs to. Tags are **organization-scoped**. |
DevHelm tags are flat — there are no nested or hierarchical tags. Express hierarchy by convention (`tier-1`, `tier-2`) or by combining tags (`team-payments` + `tier-1`).
## What you can tag
Tags are currently attachable to **monitors** via the API (`/api/v1/monitors/{id}/tags`). Tagging a monitor:
* Surfaces it in tag-filtered dashboard views.
* Feeds into [notification policy](/alerting/notification-policies) match conditions for alert routing.
* Allows tag-based filtering on incident list endpoints.
## Common tagging strategies
A small, opinionated taxonomy beats a sprawling one. The strategies below tend to age well:
| Dimension | Example tags | Purpose |
| ---------------------- | -------------------------------------- | --------------------------------------------------- |
| **Team / ownership** | `team-payments`, `team-platform` | Who pages on incidents from this monitor |
| **Tier / criticality** | `tier-1`, `tier-2`, `tier-3` | Drives escalation severity and notification routing |
| **Customer surface** | `customer-facing`, `internal` | Status-page inclusion, SLO scope |
| **Layer** | `frontend`, `api`, `database`, `infra` | Postmortem grouping, ownership rotation |
| **Compliance** | `pci`, `soc2`, `gdpr` | Scoped audit reports |
Resist the urge to tag for every possible filter; you can always add a tag later, but you cannot easily reclaim a 50-tag soup.
## Routing alerts by tag
Tags become powerful when paired with [notification policies](/alerting/notification-policies). A policy can match on any combination of tags and direct matching incidents to specific channels and escalation chains:
```yaml theme={null}
notification-policies:
- name: Payments tier-1 → PagerDuty
match:
tags: [team-payments, tier-1]
channels: [pagerduty-payments]
escalation: tier-1-rotation
```
Walkthrough: [Alert routing by tag guide](/guides/alert-routing-by-tag).
## Managing tags
1. Open **Settings → Tags**.
2. Click **Create Tag**, choose a name and (optionally) a color.
3. Apply tags from the monitor detail page, or in bulk from the monitors list view.
```bash theme={null}
devhelm tags list
devhelm tags create --name payments --color "#10b981"
devhelm tags update --color "#f59e0b"
devhelm tags delete
```
Full reference: [`devhelm tags`](/cli/commands/tags).
```yaml theme={null}
tags:
- name: payments
color: "#10b981"
- name: tier-1
color: "#ef4444"
monitors:
- name: Stripe Charge API
type: HTTP
tags: [payments, tier-1]
config:
url: https://api.stripe.com/v1/charges
```
Reference tags by name in any resource that supports a `tags:` array.
```hcl theme={null}
resource "devhelm_tag" "payments" {
name = "payments"
color = "#10b981"
}
resource "devhelm_monitor" "stripe" {
name = "Stripe Charge API"
type = "HTTP"
frequency_seconds = 60
tag_ids = [devhelm_tag.payments.id]
config = jsonencode({ url = "https://api.stripe.com/v1/charges" })
}
```
## Lifecycle and constraints
* **Renaming a tag** updates references everywhere automatically — UUIDs stay stable.
* **Deleting a tag** removes it from every monitor it's attached to. Notification policy match conditions referencing the deleted tag are flagged as broken in the dashboard until edited.
* **Tag names are unique within the organization.** Two tags with the same name cannot coexist.
* **Tags are organization-scoped.** They are visible across all workspaces in the organization.
## Reporting and filtering
* **Filter list views** by tag combinations on monitors and incidents in the dashboard.
* **Audit log search** can filter by `subject.tags` for tag-scoped activity reviews.
* **REST API** supports `tag` and `tags` query params on monitor and incident list endpoints — useful for building custom dashboards or feeding tag-filtered data into BI tools.
## Next steps
Build tag-driven notification policies.
Match on tags to route alerts.
Compare composite health vs flat tagging.
Manage from the command line.