Signals & rules
A signal is one stream of observations about a subject. A rule decides when those streams add up to an incident.
Saving website monitoring creates a subject with two things underneath it: one signal — the stream Uptimer’s own workers write their probe results into — and one rule, Reachability, which decides when those results mean an incident.
New in 1.6.0: the Custom subject. A cron job, a queue worker, a nightly export — anything that can make an HTTPS request can now report to Uptimer. Monitoring → Add Custom check creates an empty subject, you add your own signals to it, and you write your own rules over them.
Two kinds of subject
Everything a workspace watches appears in one list, and each row says which kind it is.
| Website | Custom | |
|---|---|---|
| Created by | Add Website check, or POST /v2/monitoring/websites | Add Custom check, or POST /v2/subjects |
| Starts with | One platform HTTP signal and one Reachability rule | Nothing at all |
| Signals | Owned by the website form | Add signal — heartbeat or event, as many as you like |
| Rules | Reachability only, and the check form owns its policy | Add rule — over that subject’s own signals and rules |
| Changed by | Edit, the same website monitoring form | Its Signals and Rules pages, or the API |
| Data comes from | Uptimer’s workers | You, over the API |
| Its API | /v1/rules and the /v2/monitoring/websites alias | /v2/subjects and everything nested under it |
The split is deliberate. Website monitoring is a template: a URL, an interval and a set of locations produce a probe, a signal and a rule, and the form keeps rewriting them on every save — so a signal or a rule you added there by hand would live until the next save and then vanish. A Custom subject has no form behind it, which is exactly why it is yours to compose.
So a Website subject has no Add signal and no Add rule, and its Reachability policy is edited by changing the check. Custom signals and custom rules live on Custom subjects.
The API is split the same way, and neither half serves the other’s subjects: website
monitoring is /v1/rules and its /v2/monitoring/websites alias, custom monitoring is
/v2/subjects and everything nested under it. Anything you can do on the Signals and Rules
screens you can do there too — see the REST API.
Signals
A signal is one stream of observations. Every signal belongs to a subject, and the pair (subject, signal) is the address a sender posts to.
| Kind | Who writes it | What silence means |
|---|---|---|
| Platform HTTP | Uptimer’s own workers, from the URL and interval on the website monitoring form | The source is quiet, so the input becomes no data |
| Custom heartbeat | You, on a schedule | The same — a heartbeat that stops is a problem worth seeing |
| Custom event | You, only when something happens | Nothing — quiet is normal, and the last reading stands however old |
Choosing between heartbeat and event is choosing what your silence means. A worker that pulses every 30 seconds is a heartbeat; a deploy notifier or an alert forwarder is an event.
The platform HTTP signal is created and maintained by website monitoring. It is marked built-in: you cannot delete it, and its probe stays on the website monitoring form. It is not a different kind of thing from your own signals — rules read them all the same way.
Adding one
Monitoring → a Custom subject → Signals → Add signal. Give it a name and pick heartbeat or event. The name produces the signal’s slug, which is the address senders use; renaming the signal later does not move it.
A Website subject has no Add signal: its stream is the probe, and the check form owns it. If you want your own signal beside a website check, add a Custom subject for it.
The same thing over the API is
POST /v2/subjects/{subject}/signals.
Meta is optional: any JSON object, stored and returned untouched. Uptimer never reads a key out of it — it is there for your own automation.
A new signal has received nothing, so the Signals page says so and shows the request that sends its first observation. See Reporting your own observations.
Deleting one
A signal a rule reads cannot be deleted — the page says which rules and links to them. Remove it from those rules first. Uptimer never unlinks a rule on its own, because that would quietly change what the rule watches in order to complete an unrelated delete.
Observations
One observation is one report: a status (ok or problem), an optional numeric value,
an optional error string, and an open map of labels you choose.
Labels are yours. Uptimer stores them and rules match on them; there is no dictionary to
register. One key is reserved: location, which is what the platform HTTP signal’s workers use
to say where they probed from.
An observation is identified by its signal, its observed_at and its labels. Re-sending the
same one replaces it rather than counting twice, so a retry after a timeout is safe.
Uptimer keeps every observation it accepts and also the ones it will not evaluate — a report
stamped too far in the future, say. Those come back with accepted: false and a
reject_reason, and are visible in the signal’s log. Storing them is deliberate: “we ignored
this, and here is why” is a different answer from “we never heard you”.
What an observation costs
Self-hosted Uptimer does not meter or bill observations. Send as many as your database and retention are happy with; nothing here counts them.
On the hosted service at myuptime.info the unit is one accepted observation, and it is the same unit whatever produced it — a platform HTTP probe, a custom heartbeat, or a custom event. Observations that are stored but not accepted use no units, and a retry that replaces a row does not add one. Current allowances and prices are on the hosted pricing page.
Rules
A rule takes some inputs, decides how many of them must look like a problem, and holds that
answer before it becomes an incident. Monitoring → a Custom subject → Rules → Add rule, or
POST /v2/subjects/{subject}/rules. A subject
needs a signal before it can have a rule, so add the signal first.
Inputs
An input reads one of the subject’s own signals, or another of its rules. Cross-subject inputs are not possible — a subject is the boundary. That is also why the editor is a Custom-subject surface: the signals it can offer are the ones on the subject you are editing.
For a signal input you choose which observations it selects with free-text label keys and
values. A value of * means the key must be present with any value; no filters at all selects
the whole signal.
For a rule input, the cited rule’s own verdict is the input: problem is true, ok is false, and no data is unknown. Prerequisites are evaluated before the rules that read them, so a chain settles in one pass.
What counts as a problem
Each signal input picks exactly one:
- Status — the latest selected observation reports
problem. - Latest value — the latest selected numeric
valueis<or>one threshold. Observation status is ignored in this mode, and an observation with no number is unknown rather than false.
How many must agree
Any, Majority, All, or At least N. A rule with no inputs cannot report health, so it reads as no data.
Unknown inputs do not drag a settled answer down: once enough inputs are true the verdict is problem, whatever the rest are doing.
Timing
Confirm after is how long a rule must stay bad before the incident is confirmed and anyone is alerted — the incident opens on the first bad tick regardless. Close after is how much continuous recovery closes it. Both default to two minutes.
No data after is per input: how long that input may stay silent before it counts as unknown. Leave it empty to derive it from the check’s interval. Event signals do not offer it — their silence is not a fault.
Reachability
The rule website monitoring creates is the same kind of rule, evaluated the same way — but it is owned by the check form, not by the rules editor. Its inputs are the locations the check watches, one input each, and how many of them must fail is the form’s Locations Required to Fail. Change the check, and the policy is rewritten to match.
So on a Website subject you can open Reachability and read what it is doing, but there is no edit and no delete: the check form is where it changes, and it is part of what the check means.
Where to go next
- Report an observation — the API and a runnable curl.
- Python SDK — the same call, typed.
- Monitors & incidents — how a verdict becomes an incident, and the badges the dashboard shows.