1.2Quickstart: your first monitor and alert

In this walkthrough you set up an alert channel and a URL monitor. The monitor checks a health endpoint, a page whose only job is to report that your service is running. You can use the dashboard or the API.

Step 1: Create an alert channel#

Select alerting → channels → + new channel. The New alert channel panel opens.
Choose the channel type. Slack is selected at first. For this example, choose Email.
In Name, enter a name you will recognise later, for example ops-team.
In Email address, enter one address, for example ops@example.com.
Select Create channel.
Open the new channel and select send test to check that alerts arrive.

Each email channel takes one address. To alert several people, add one channel per address. For Slack, paste the incoming webhook URL from your Slack app. It must start with https://. Otherwise the form shows Must be an https URL. Chapter 10 covers every channel type.

Step 2: Create a URL monitor#

Select + new monitor in the top navigation.
In the row of monitor types at the top, select url. You cannot change a monitor's type later.
In name, enter a name you will recognise in an alert, for example acme.io — health.
Under request, keep the method GET. Enter the address to check, for example https://acme.io/health.
Look at check interval. The form starts at 60 seconds. Your plan's minimum still applies, and the form shows it under the field.
Check timeout. The form starts at 10 seconds.
Under locations, select the regions to check from. If you select none, obsrvly uses us-west.
Under on failure — notify, select the channel you created in step 1.
Under assertions, keep the first row: status_code eq 200. An assertion is a rule the reply must meet. Chapter 4 covers assertions.
Select create monitor →.

If the form shows a message, fix the field and try again:

Message	What to do
`Give it a name`	Enter a name. It can be up to 200 characters.
`A URL is required`	Enter the address to check.
`Start with http:// or https://`	Add `https://` (or `http://`) to the start of the address.
`No spaces in a URL`	Remove the spaces from the address.
`Your plan checks at most every N seconds`	Enter an interval of at least N seconds.

Step 3: Read the result#

Open dashboard. Your monitor shows Pending (PEND in the list) until its first check runs. Then it shows Up, Down or Degraded. Open the monitor to see Recent checks, the latest results with their region.

Step 4: Know what happens when it fails#

By default, obsrvly opens an incident after 2 failed checks in a row. It then alerts the channels attached to the monitor. When the check passes again, obsrvly sends a resolved notice. You find incidents under alerting → incidents.

Do the same with the API#

First create an API key in the dashboard: secrets → api keys. The key is shown only once, so copy it straight away. You cannot create a key with another key.

Set two variables in your shell. Then create an email channel:

Create an email channel

bash

export OBSRVLY_KEY=obs_...
export OBSRVLY=https://www.obsrvly.com/api/gw

curl -s "$OBSRVLY/monitor/obsrvly.v1.MonitorConfigService/CreateEmailChannel" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ops-team", "emailTo": "ops@example.com"}'

The reply contains channel.id. Use it in place of <channel-id> to create the monitor:

Create a URL monitor

bash

curl -s "$OBSRVLY/monitor/obsrvly.v1.MonitorConfigService/CreateUrlMonitor" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "acme.io — health",
       "url": "https://acme.io/health",
       "method": "GET",
       "intervalSeconds": 300,
       "locations": ["us-west"],
       "alertChannelIds": ["<channel-id>"]}'

To read the latest results, send the monitor's ID:

List recent check results

bash

curl -s "$OBSRVLY/result/obsrvly.v1.ResultService/ListExecutions" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monitorId": "<monitor-id>", "limit": 20}'

To list incidents, call ListIncidents in the alert area. You can filter by status: firing or resolved.

The dashboard and the API behave differently in a few places:

Setting	Dashboard	API
Check interval	Starts at 60 seconds.	Required. Leaving out `intervalSeconds` fails with `interval_seconds must be > 0`.
Assertions	Starts with `status_code` `eq` `200`.	With no assertions, any 2xx status code counts as up.
Method	Starts at `GET`.	Leaving out `method` means `GET`.
Timeout	Starts at 10 seconds.	Leaving out `timeoutMs` uses 30 seconds for URL monitors (see 3.1 for other types).
Regions	None selected means `us-west`.	Leaving out `locations` means `us-west`.
Run a check now	run once now on the edit page.	`TriggerNow`, once per monitor every 30 seconds.

If the interval is below your plan's minimum, the API replies with failed_precondition. Your plan's minimum still applies.
A misspelled field name fails with invalid_argument. The message names the field.
Every reply has an X-Request-Id header. Quote it when you ask for help.