# Monitoring alerts

> Get an email when an instance's CPU or disk use runs high, its data transfer passes an amount, or it goes down.

Source: https://www.coritan.com/docs/cloud-compute/alerts/

In the dashboard:

- /dashboard/compute/…/alerts: https://www.coritan.com/dashboard/compute

An *alert* watches one thing on an instance and emails you when it goes past the limit you set. It emails you again when it clears. An alert never changes anything on the instance. Alerts cost nothing.

## Add an alert

Open the instance, go to its **Alerts** tab and choose **Add alert…**. Choose what to watch:

| Alert on | Goes off when | Checked |
| --- | --- | --- |
| CPU use | The instance uses more than the percent you set of its vCPUs, for at least the minutes you set | Every minute |
| Disk use | The fullest filesystem inside the instance is fuller than the percent you set | Every 10 minutes |
| Data transfer this month | Data in and out since the first of the month passes the GB you set | Every minute |
| Down | The instance stops without you stopping it, for at least the minutes you set | Every minute |

For a CPU or down alert, the minutes keep a short spike from setting it off. CPU waits 5 minutes unless you choose otherwise, and down waits 3.

A down alert can also name a port. We then try to connect to that TCP port on the instance's IPv4 address every minute, and call the instance down when it does not answer. Use the port your service listens on, such as 443 for a website or 22 for SSH. Your firewall must let connections to it through.

An instance holds up to 10 alerts.

## What each alert needs

- **Disk use** reads the filesystems through the QEMU guest agent. Our images have it. On an image of your own, install and start `qemu-guest-agent`, or the alert shows **Unknown** with the reason.
- **Down** knows when you stopped the instance yourself, from the dashboard or the API, and does not go off then.
- **Data transfer this month** goes off once a month at most, and clears on the first of the next month.

## What the tab shows

Each alert shows where it stands now:

- **OK**: within its limit.
- **Over the limit**: past its limit, and waiting out its minutes before it goes off.
- **Firing**: it has gone off and we emailed you.
- **Unknown**: we could not read the value, with the reason. An unknown alert never goes off. When we cannot reach the host the instance runs on, a down alert is unknown, not down.
- **Paused**: you paused it.

Its last reading and when we took it are beside it. The **History** below lists when each alert went off and cleared, and whether we sent the email.

From an alert's menu you can pause it, stop or start its emails, or delete it. Deleting an alert keeps its history.

## With the API

```bash
curl -X POST https://api.coritan.com/api/v1/client/vps/$INSTANCE_UUID/alerts \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"metric": "cpu", "threshold": 90, "duration_minutes": 10}'
```

`metric` is `cpu`, `disk`, `bandwidth` or `down`. `threshold` is a percent for `cpu` and `disk` (1 to 100) and GB for `bandwidth`; `down` takes none. `duration_minutes` (1 to 1440) applies to `cpu` and `down`, and `port` only to `down`. A field out of range answers `422` and says which, and an eleventh alert answers `409`.

`GET /api/v1/client/vps/{uuid}/alerts` answers the alerts with their `state`, `last_value`, `last_detail` and `last_checked_at`, the last 50 events, and the metrics with their ranges. `PATCH .../alerts/{rule_uuid}` takes `threshold`, `duration_minutes`, `port`, `enabled` and `notify_email`. A changed limit starts the alert over at OK.

## What is not included

- Alerts by text message, chat or webhook. We send email only.
- Memory use. The host cannot see how much memory the instance's own system uses.
- Checks from more than one place. We check from Coritan's network.

## API

- `GET /api/v1/client/vps/{uuid}/alerts`: List alerts (https://www.coritan.com/docs/api/reference/client/cloud-compute-alerts/#op-get-api-v1-client-vps-uuid-alerts)
- `POST /api/v1/client/vps/{uuid}/alerts`: Add an alert (https://www.coritan.com/docs/api/reference/client/cloud-compute-alerts/#op-post-api-v1-client-vps-uuid-alerts)
- `PATCH /api/v1/client/vps/{uuid}/alerts/{rule_uuid}`: Change an alert's threshold, duration or port, pause it, or stop its emails (https://www.coritan.com/docs/api/reference/client/cloud-compute-alerts/#op-patch-api-v1-client-vps-uuid-alerts-rule-uuid)
- `DELETE /api/v1/client/vps/{uuid}/alerts/{rule_uuid}`: Delete an alert (https://www.coritan.com/docs/api/reference/client/cloud-compute-alerts/#op-delete-api-v1-client-vps-uuid-alerts-rule-uuid)