# Alarm on a custom metric

Put an alarm on a series you publish yourself, named by its namespace, metric name and dimensions.

An alarm on a custom series names the series rather than a resource: `resourceType` `custom`,
`resourceId` the namespace, `metric` the metric name, and `dimensions` exactly the series'
dimensions. A series with other dimensions is another series. The series need not exist yet: until
it has datapoints in the evaluated periods, the alarm is `INSUFFICIENT_DATA`.

You can also alarm on a namespace the platform writes for you, such as `EWS/Scheduler`.

## Prerequisites

- Permission for `monitoring:PutMetricAlarm` on `rn:ews::<organization id>:monitoring:*`.

## Create the alarm

**Console:** not available. The console's alarm form lists resources, not custom series.
**CLI**
```sh
dcloud monitoring alarms create --name "Checkout slow" --resource-type custom \
  --resource-id Shop --metric checkout_ms --dimensions route=/pay \
  --statistic avg --comparator ">" --threshold 500 --period-seconds 300 \
  --evaluation-periods 2 --notify-emails ops@example.com
```

**API**
```http
POST /monitoring/api/alarms
{
  "name": "Checkout slow",
  "resourceType": "custom",
  "resourceId": "Shop",
  "metric": "checkout_ms",
  "dimensions": { "route": "/pay" },
  "statistic": "avg",
  "comparator": ">",
  "threshold": 500,
  "periodSeconds": 300,
  "evaluationPeriods": 2,
  "notifyEmails": ["ops@example.com"]
}
```

**Terraform**
```hcl
resource "dcloud_monitoring_alarm" "checkout_slow" {
  name               = "Checkout slow"
  resource_type      = "custom"
  resource_id        = "Shop"
  metric             = "checkout_ms"
  dimensions         = { route = "/pay" }
  statistic          = "avg"
  comparator         = ">"
  threshold          = 500
  period_seconds     = 300
  evaluation_periods = 2
  notify_emails      = ["ops@example.com"]
}
```

## Alarm when something stops

A missing datapoint never crosses a threshold, so an alarm on a series that stops arriving goes to
`INSUFFICIENT_DATA`, not to `ALARM`. Publish a zero while there is nothing to count
(`orders_placed` with `value: 0`) and alarm on `sum < 1`.

## When the alarm is refused

- `400` "dimensions: Dimensions are for custom metrics only" when an alarm on a resource names
  dimensions.
- `400` "resourceId: For a custom metric, resourceId is its namespace (letters, digits and . \_ / # :
  -)".
- `409` when the name is taken, as for any alarm.

## Related

- [How alarms work](how-alarms-work.md)
- [Publish custom metrics](publish-custom-metrics.md)
- `monitoring.alarms.create` · `dcloud_monitoring_alarm`
