Monitors as code
Keep your monitors in openping.yml, next to the code they watch, and if you like the status page and alert rules that go with them. They are reviewed like code, and the repo stays the source of truth.
An example
This is the file one of our own products uses: a web check, an agent test, a heartbeat and an MCP monitor.
service: taskos
defaults:
regions: [mumbai, frankfurt, virginia]
every: 1m
alert: taskos-oncall
monitors:
- name: Web app
type: http
url: https://tasks.supertuned.ai/api/health
expect:
status: 200
latency: { under: 1500ms }
- name: Chat answers
type: agent
endpoint: https://tasks.supertuned.ai/api/chat
auth: { bearer: secret.TASKOS_TEST_TOKEN }
every: 1h
cases:
- ask: "What's due today?"
expect:
- answered: { within: 20s }
- not_contains: "error"
- judge: "Lists the tasks due today, or says there are none."
- name: Meeting notes read
type: heartbeat
schedule: "50 10 * * 1-5"
timezone: Asia/Kolkata
grace: 15m
- name: OpenPing MCP
type: mcp
url: https://mcp.openping.ai
auth: { oauth: client_credentials, secret: secret.OPENPING_MCP_CLIENT }
expect:
tools: { includes: [list_monitors, create_monitors] }
on_change: alert
call:
tool: list_monitors
args: { limit: 1 }The flow
openping init # reads the project, writes openping.yml
openping test # runs every monitor now, from this machine
openping deploy # shows the plan, asks, then applies itdeploy prints what it will do before it does it: + add, ~ change and - remove. Only the monitors, status pages and alert rules that came from this file, in this service, are ever changed or removed. The ones you made in the app are left alone.
The file
service: the name of the product or part these monitors belong to.defaults:regions,every,alert(an alert rule’s name) andtimeout, used by any monitor that doesn’t set its own.monitors: up to 500. Each has anameand atype; the rest depends on the type.alert_rulesandstatus_pages: optional. See status pages and alert rules below.
| Key | Used by | Meaning |
|---|---|---|
url, endpoint, host, domain | All but heartbeat | What to check |
every, timeout, grace | All | A duration: 30s, 1m, 1h, 1500ms |
regions, severity, tags, alert | All | Where from, how loud, labels, and which alert rule |
method, headers, body | http; headers and body for agent too | The request to send. For an agent, body is the whole JSON body with {{ask}} where the question goes |
auth | http, mcp, agent | { bearer: secret.NAME }, basic, header, or { oauth: client_credentials, secret: secret.NAME } |
expect | http, mcp, gateway | status, latency, contains, not_contains, regex, json, header, cert_days, tools, on_change, first_token |
cases, samples, target, protocol, model | agent | The questions and how answers are judged |
schedule, timezone | heartbeat | A cron expression and its time zone |
call | mcp | The safe test call: tool, args |
models, api_key | gateway | Which models get the tiny streamed reply |
request | gateway | Your app’s real request: params, headers, path. See gateway monitors |
records, mail | dns | Record types to watch; also check SPF and DMARC |
port | tcp, cert | The port to connect to |
A key the file doesn’t know is an error, not a silent skip. A mistake is reported with its place: monitors[2].every: use a duration like 30s, 1m or 1h.
Status pages and alert rules
A repo can hold the whole setup: the alert rules its monitors use, and the status page they drive. Add two sections beside monitors. This is the rest of the TaskOS file above:
alert_rules:
- name: TaskOS on-call
steps:
- afterMinutes: 0
channels: ["#taskos-alerts"]
- afterMinutes: 15
channels: [Email]
escalationPolicy: TaskOS primary
repeatMinutes: 30
status_pages:
- name: TaskOS status
slug: taskos
customDomain: status.supertuned.ai
published: true
components:
- name: Web app
monitors: [Web app]
- name: Chat
group: AI
monitors: [Chat answers]
- name: Meeting notes
monitors: [Meeting notes read]- Each takes the same fields as the API, with names where the API takes ids: a rule step names its
channels, a rule names itsescalationPolicy, a component names itsmonitors. Monitors name a rule inalert, as before. - Channels are added in the app, because they hold secrets. The file names them, and a name it cannot find is an error with its place in the file.
- A field you leave out keeps its value. A file that never says
publishedcannot take a page private, and one that never namescustomDomaincannot take your domain away. - A component may name a monitor in this file, or one you made in the app. The order of the list is the order on the page.
- When the file drops a page or a rule,
deployremoves it, like a monitor. It never removes the default alert rule, and never one made in the app or by another service’s file. - A new
customDomainstill has to be proven: the first deploy prints the TXT record to add. Then add the CNAME the page shows, and the page’s settings say when it is live. See your own domain.
Secrets never go in the file
Write secret.NAME where a token goes. On our side the value comes from your organisation’s secrets. When you run openping test locally, secret.NAME is read from the environment variable $NAME. deploy tells you which secrets are missing before it applies anything.
In CI
name: openping
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npx openping test
- run: npx openping deploy --yes
env:
OPENPING_API_KEY: ${{ secrets.OPENPING_API_KEY }}See the CLI for every command.