# Metrics

The metrics the platform records for each kind of resource, how often, how long it keeps them, and how a chart or an alarm combines them.

A metric is one measurement of one resource over time. A resource is named by a resource type and
an id, as `GET /monitoring/api/resources` (`dcloud monitoring metrics resources`) lists them.
Nothing is installed on your machines for these metrics.

## Resource types and their metrics

| Resource type      | What it is                                                                                                | Metrics                                                                                                                                                                        |
| ------------------ | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `instance`         | A compute instance, including the machines your apps and cluster nodes run on                             | `cpu_percent`, `disk_read_iops`, `disk_write_iops`, `disk_read_bps`, `disk_write_bps`, `network_in_bps`, `network_out_bps`                                                     |
| `db_node`          | One machine of a Managed PostgreSQL database or a Document Database cluster; a cluster has one per member | The seven above, and `disk_used_percent`, `connections`, `replication_lag_bytes`, `query_slowdown`, `docdb_up`                                                                 |
| `vpn_connection`   | A site-to-site VPN connection                                                                             | `tunnel_up`, `tunnel_in_bps`, `tunnel_out_bps`, `bgp_prefixes`                                                                                                                 |
| `eks_cluster`      | A Kubernetes cluster                                                                                      | `api_available`, `control_plane_ready`, `nodes_ready`, `nodes_not_ready`                                                                                                       |
| `cdn_distribution` | A CDN distribution, every edge location together                                                          | `cdn_requests`, `cdn_cache_hits`, `cdn_cache_misses`, `cdn_hit_ratio`, `cdn_bytes_out`, `cdn_origin_bytes`, `waf_blocked`, `waf_counted`, `waf_challenged`, `waf_rate_limited` |
| `app`              | An app's deployments, one point per finished deployment                                                   | `deploy_duration_seconds`, `deploys_succeeded`, `deploys_failed`                                                                                                               |

`GET /monitoring/api/metrics?resourceType=…&resourceId=…` lists every metric a resource type
records, with its label, its unit and when it was last recorded (`null` when it has no point in the
last 14 days).

## How the machine metrics read

- The machine metrics of an instance or a database node are the provider's figures, collected once
  a minute.
- `cpu_percent`: 100 is one vCPU fully busy, so a machine with four vCPUs reaches 400.
- The disk metrics are the machine's local disk, and the network metrics its public interface. A
  database's data volume is `disk_used_percent`, which the node reports every few minutes.
- `connections`, `replication_lag_bytes` and `docdb_up` arrive every two minutes, and
  `query_slowdown` every five while `pg_stat_statements` is on. `replication_lag_bytes` is not
  recorded for the leader; `docdb_up` is recorded for Document Database nodes only.
- Only running machines are collected. A stopped machine records nothing: its chart shows a gap,
  not zero.
- `deploys_succeeded` and `deploys_failed` record 1 when a deployment goes live or fails;
  `deploy_duration_seconds` is the time from queued to live or failed.

Every metric's description is on the alarm form when you choose it, and in the `metric` field of
the _API Reference_.

## Periods and statistics

A chart or an alarm groups the points into periods, a whole number of minutes from 1 minute to one
day, and takes one statistic of the points in each period. An alarm takes `avg` (the default),
`max`, `min`, `sum` or `count` (the number of points). Reading a resource's datapoints
(`GET /monitoring/api/metrics/data`) takes `avg` (the default), `max` or `min`; `sum` and `count`
are accepted there but answer the average. A period with no point has no datapoint; it is left out
of the answer.

## Retention

Points are deleted once a day when they are older than 14 days. A resource that no longer exists
keeps its points until then.

## Related

- [Read a resource's metrics](read-metrics.md)
- [Publish custom metrics](publish-custom-metrics.md)
- [How alarms work](how-alarms-work.md)
