# Get started with Monitoring

Publish a custom metric, put an alarm on it, check a URL from outside, read the result, and delete what you made, in about ten minutes.

Replace _https://example.com/_ with a URL of your own, and _alarm-id_ and _check-id_ with the ids
the create steps return. Nothing here touches a machine.

## Prerequisites

- Permission for `monitoring:PutMetricData`, `monitoring:PutMetricAlarm`,
  `monitoring:CreateCheck`, `monitoring:GetCheckResults`, `monitoring:DeleteAlarms` and
  `monitoring:DeleteChecks`.
- In the console, also `monitoring:DescribeAlarms` to open **Alarms** and
  `monitoring:DescribeChecks` to open **Uptime** and the check's page; without them the list pages
  show an access-denied notice and the check's page is not found.
- For the CLI steps, the dcloud CLI, signed in. For the API steps, an access key.

## Step 1: Publish a datapoint

A custom series exists from its first datapoint on. The points you keep are metered storage.

**Console:** not available. The console charts custom metrics but does not publish them.
**CLI**
```sh
dcloud monitoring custom-metrics put --namespace Shop \
  --metric-data '{"metricName":"orders_placed","value":1}'
```

**API**
```http
POST /monitoring/api/custom-metrics
{ "namespace": "Shop", "metricData": [{ "metricName": "orders_placed", "value": 1 }] }
```

The answer is `{ "success": true, "data": { "accepted": 1, "rejected": [] } }`. Under **Monitoring**, **Custom metrics**, the
namespace `Shop` now lists the series `orders_placed`.

## Step 2: Alarm on the series

The alarm fires when fewer than one order is placed in a five-minute period.

**Console:** not available. The console creates alarms on machines and other resources only, not on custom series.
**CLI**
```sh
dcloud monitoring alarms create --name "No orders" --resource-type custom \
  --resource-id Shop --metric orders_placed --statistic sum --comparator "<" \
  --threshold 1 --period-seconds 300
```

**API**
```http
POST /monitoring/api/alarms
{ "name": "No orders", "resourceType": "custom", "resourceId": "Shop", "metric": "orders_placed",
  "statistic": "sum", "comparator": "<", "threshold": 1, "periodSeconds": 300 }
```

The answer is `201` with the alarm in `INSUFFICIENT_DATA`. It is evaluated every minute; read its
state and the reason with `dcloud monitoring alarms get alarm-id`. While the evaluated
period has no datapoint it stays `INSUFFICIENT_DATA`: a missing datapoint never counts as fewer
than one (see [How alarms work](how-alarms-work.md)).

## Step 3: Check a URL

**Console**
1. Open **Monitoring**, then **Uptime**, and choose **Create check**.
2. For **Name**, enter Example.
3. For **URL**, enter https://example.com/.
4. Choose **Create check**.

The check appears in the list in the `pending` state.

**CLI**
```sh
dcloud monitoring checks create --name Example --url https://example.com/
```

**API**
```http
POST /monitoring/api/checks
{ "name": "Example", "url": "https://example.com/" }
```

The check runs within a minute, then every five minutes. If the answer is `409` with "… is already
checked … times a minute by …", other checks already request that host as often as the platform
allows; use a URL of your own.

## Step 4: Read the result

**Console**
1. In **Uptime**, choose the check's row.
2. The page shows the state and why, and under **Response time** the share of runs that succeeded
   and the response times. **Latest results** lists each run from each location.

**CLI**
```sh
dcloud monitoring checks results check-id
```

**API**
```http
GET /monitoring/api/checks/check-id/results
```

After its first run the check is `up`, `regional` or still `pending`; it becomes `down` only after
two failed runs in a row (see [How uptime checks work](how-uptime-checks-work.md)).

## Clean up

Delete the alarm and the check. The custom series cannot be deleted: with no new datapoints, its
minute points are removed after 15 days and the series after 15 months.

**Console**
1. In **Alarms**, open the action menu of the alarm _No orders_, choose **Delete alarm**, then
   **Delete**.
2. In **Uptime**, open the action menu of the check, choose **Delete check**, then **Delete**.

**CLI**
```sh
dcloud monitoring alarms delete alarm-id
dcloud monitoring checks delete check-id
```

**API**
```http
DELETE /monitoring/api/alarms/alarm-id
```

```http
DELETE /monitoring/api/checks/check-id
```

## Next steps

- [Create an alarm](create-an-alarm.md) on a machine
- [Publish custom metrics](publish-custom-metrics.md)
- [Create a status page](create-a-status-page.md)
