# Create an alarm

Watch one metric of an instance, a database node or another resource, and get a mail or a webhook call when it crosses a threshold.

Replace _i-1a2b3c4d_ with the id of the resource, as `dcloud monitoring metrics resources` lists
it. For how the alarm decides its state, see [How alarms work](how-alarms-work.md); for a series
you publish yourself, see [Alarm on a custom metric](alarm-on-a-custom-metric.md).

## Prerequisites

- Permission for `monitoring:PutMetricAlarm` on `rn:ews::<organization id>:monitoring:*`. Without
  it, the console's **Create alarm** is unavailable, with the note "Creating an alarm needs
  monitoring:PutMetricAlarm. Ask an administrator."
- In the console, also `monitoring:DescribeAlarms` to open **Alarms** (without it the page shows an
  access-denied notice) and `monitoring:ListMetrics` to list the resources (without it the form
  says "Listing machines needs monitoring:ListMetrics. Ask an administrator.").

## Create the alarm

**Console**
1. Open **Monitoring**, then **Alarms**, and choose **Create alarm**.
2. For **Name**, enter web-1 CPU high.
3. For **Machine**, choose the resource: an instance, a database node, a VPN tunnel, a Kubernetes
   cluster, a CDN distribution or an app's deployments.
4. For **Metric**, choose one of the metrics the resource records. Its description appears under
   the field.
5. For **Statistic**, choose **Average**, **Maximum** or **Minimum**, and in the field next to it,
   the comparison.
6. For **Threshold**, enter the value, in the unit shown under the field.
7. For **Period**, choose **1 minute**, **5 minutes** (the default), **15 minutes** or **1 hour**,
   and for **For this many periods**, enter 1 to 100.
8. (Optional) For **Email addresses (optional)**, enter up to ten addresses, separated by commas or
   spaces, and for **Webhook URL (optional)**, an `https://` URL.
9. Choose **Create alarm**.

The alarm appears in the list in **Insufficient data**. The sum and sample-count statistics, and
periods other than those four, are available in the CLI, the API and Terraform.

**CLI**
```sh
dcloud monitoring alarms create --name "web-1 CPU high" --resource-type instance \
  --resource-id i-1a2b3c4d --metric cpu_percent --statistic avg --comparator ">" \
  --threshold 80 --period-seconds 300 --evaluation-periods 3 \
  --notify-emails ops@example.com --webhook-url https://hooks.example.com/ews
```

**API**
```http
POST /monitoring/api/alarms
{
  "name": "web-1 CPU high",
  "resourceType": "instance",
  "resourceId": "i-1a2b3c4d",
  "metric": "cpu_percent",
  "statistic": "avg",
  "comparator": ">",
  "threshold": 80,
  "periodSeconds": 300,
  "evaluationPeriods": 3,
  "notifyEmails": ["ops@example.com"],
  "webhookUrl": "https://hooks.example.com/ews"
}
```

`periodSeconds` is required; `statistic` defaults to `avg` and `evaluationPeriods` to 1.

**Terraform**
```hcl
resource "dcloud_monitoring_alarm" "web_cpu" {
  name               = "web-1 CPU high"
  resource_type      = "instance"
  resource_id        = dcloud_instance.web.id
  metric             = "cpu_percent"
  statistic          = "avg"
  comparator         = ">"
  threshold          = 80
  period_seconds     = 300
  evaluation_periods = 3
  notify_emails      = ["ops@example.com"]
}
```

## Result

The alarm starts in `INSUFFICIENT_DATA` and is evaluated every minute. It mails its addresses and
calls its webhook when it enters `ALARM` and when it leaves it.

## When the alarm is refused

- `409` "An alarm named "web-1 CPU high" already exists": names are unique in the organization.
- `404` "Resource not found": your organization has no resource of that type with that id.
- `400` "disk_used_percent is not recorded for a instance": the resource type does not record the
  metric.
- `400` when period × evaluation periods passes one day ("evaluationPeriods: An alarm looks back at
  most one day (period × evaluation periods)"), when the period is not a whole number of minutes
  from 1 minute to a day, or when the webhook URL is not allowed (see
  [Notification webhooks](notification-webhooks.md)).

## Related

- [How alarms work](how-alarms-work.md)
- [Change an alarm](change-an-alarm.md)
- `monitoring.alarms.create` · `dcloud monitoring alarms create` · `dcloud_monitoring_alarm`
