# Create an alarm

Define alarm rules in the UI, preview thresholds, and notify channels when metrics cross a condition.

Alarms watch workspace metrics and change state when an expression is true for enough datapoints in an evaluation window. Use them for operational signals that need attention, such as high latency, missing throughput, queue growth, or error spikes.

An alarm belongs to the current workspace. It can use metrics from that workspace and notify workspace notification channels.

## What alarms are for

Use alarms when a metric condition should produce an operational signal, not just a chart.

Good alarm rules are specific and actionable. For example:

- API latency is above a threshold for several datapoints.
- Error rate is higher than expected while traffic is present.
- Queue depth keeps growing.
- A periodic job stops reporting samples.

Dashboards help you inspect data. Alarms help you notice when the data needs action.

## Create an alarm

Open **Alarms** from the app sidebar, then select **New Alarm**.

Enter a name that describes the condition, such as `checkout-latency-high` or `worker-queue-depth`. Alarm names are used in URLs and API calls, so prefer stable names that are easy to recognize.

## Add metric variables

An alarm expression uses one or more variables. Each variable selects a metric and aggregation, similar to a dashboard chart variable.

For each variable:

- choose a variable name, such as `var1`, `latency`, or `errors`;
- select the metric to read;
- select the aggregation, such as `avg`, `max`, `count`, `percentile(95)`, or `trimmed_mean(10;10)`;
- set percentile or trimmed-mean bounds when the aggregation needs parameters;
- add dimension filters when the alarm should only evaluate a subset of the metric.

Use **Add Variable** when the expression needs multiple signals. For example, one variable can represent errors and another can represent requests.

## Write the expression

The expression decides when the alarm should fire. It can compare variables to numbers and combine conditions.

Examples:

```text
latency > 500
errors > 10 and requests > 100
queueDepth > 1000
```

Use the variable names you defined in the variables section. The UI validates the expression and shows a preview with threshold reference lines when it can extract them.

## Choose evaluation settings

The **Evaluation Period** is the time window, in minutes, used to decide the alarm state.

**Datapoints to Alarm** is how many datapoints inside that window must breach the expression before the alarm changes to an alarm state.

Use more than one datapoint for noisy metrics so a single spike does not page the team. Use a shorter period and fewer datapoints for conditions that need fast reaction.

The **Resolution** controls the metric rollup interval used by the alarm. Match it to the expected reporting frequency of the metric. A service that reports every minute usually works well with `1m`; high-frequency metrics may use shorter resolutions.

See [Metric rollups and resolution](/docs/metric-rollups-resolution) for how alarm buckets affect aggregations and sensitivity.

## Treat missing data

Use **Treat Missing Data As** to decide what happens when the alarm cannot evaluate enough datapoints in the current window.

This can happen when a metric has not reported yet, when some buckets in the window are empty, or when one side of a variable-to-variable expression is missing data. For example, if **Datapoints to Alarm** is `5` but only `3` datapoints are present in the window, the alarm does not have enough data to make a normal `OK` or `IN_ALARM` decision.

Choose one of these options:

- **Show insufficient data** stores the alarm as `INSUFFICIENT_DATA`.
- **Treat as breaching** stores the alarm as `IN_ALARM`.
- **Treat as not breaching** stores the alarm as `OK`.

In the API, this setting is named `treatMissingDataAs`. The allowed values are `MISSING`, `BREACHING`, and `NOT_BREACHING`.

## Notify channels

Use **Notification Channels** to choose which channels should receive alarm state changes.

The alarm form loads the available notification channels in the current workspace. Check each channel that should receive notifications. Each row shows the channel name, type, and target email or webhook URL.

If no channels are available, create one from **Notification Channels** first, then return to the alarm.

Create and verify notification channels before selecting them for an alarm. The form may list an unverified email channel, but the API rejects an alarm that references it.

## Review and save

The preview uses the selected metric variables and the last hour of data. Use it to check that the selected aggregation, filters, and threshold make sense before saving.

Select **Create Alarm** when the rule is ready. The app opens the alarm detail page after creation.

## Manage alarms

Open **Alarms** to review configured alarms and their current status.

Open an alarm to inspect its configuration. Select **Edit Alarm** to change the rule, or **Delete** to remove it.

## Permissions

Creating and managing alarms requires a role that allows the relevant alarm actions in the current workspace.

See [Create and use roles](/docs/roles) for custom role policies, and [Create an API token](/docs/tokens) if automation should create or manage alarms through the API.