---
id: monitors
title: Monitors
sidebar_label: Monitors
---

Monitors check that something is answering. Four types, two places they can run
from, and a notification path when they stop being satisfied.

## Types

| Type   | Checks                                  | Options                                                                           |
| ------ | --------------------------------------- | --------------------------------------------------------------------------------- |
| `http` | An HTTP(S) URL                          | method, expected status, keyword that must appear in the body, allow insecure TLS |
| `tcp`  | A host and port accept a connection     |                                                                                   |
| `icmp` | A host answers ping                     |                                                                                   |
| `tls`  | A certificate is valid and not expiring | warn N days before expiry                                                         |

An `http` monitor with a keyword is usually the one you want for an application:
a 200 that returns an error page still fails the keyword.

## Where a check runs

Every monitor has a **runner**:

| Runner      | Meaning                                                        |
| ----------- | -------------------------------------------------------------- |
| `server`    | The control plane's scheduler performs the check               |
| a server ID | That server's agent performs it locally and reports the result |

Use `server` for anything reachable from the control plane public endpoints,
your own front door. Use an agent for anything only reachable from inside the
target network: a database on a private subnet, a service bound to localhost, a
device on a management VLAN.

:::tip Agent-run monitors measure what your users can't
A check run from the control plane tells you the service is reachable from
there. A check run on the machine tells you the process is alive. Those are
different questions, and outages usually live in the gap.
:::

## Interval, retries and state

- **Interval** how often to check.
- **Retries** how many consecutive failures are tolerated before the state
  flips.

A monitor sits in `pending` until its first result. Failures accumulate; once
they exceed `retries`, the monitor goes `down`, an **incident** opens and the
attached notification channels fire. A subsequent success closes the incident.

Retries are what keeps one dropped packet from paging you. Set them to at least
`1` for anything crossing the public internet.

## Notifications

Attach one or more [notification channels](./notification-channels.md) to a
monitor. Channels are shared, so one Slack destination can serve every monitor
you have.

Notification state is tracked per monitor, so a service that is down for six
hours does not send a message per interval.

## Uptime and incidents

The monitor detail page shows:

- **Uptime**, from hourly rollup records checks performed, how many were up,
  and mean latency per hour. Rollups are what make the graph cheap to draw over
  long windows.
- **Incidents**, each with a start, a resolution and the cause recorded at the
  moment it opened.

## Disabling versus deleting

Disabling stops the checks and keeps the history. Deleting removes the monitor.
Prefer disabling for anything seasonal the uptime record is usually the part
you wanted.
