4.1How assertions work

A response can arrive and still be wrong. It might be an error page, an empty list, or a page without its security headers. An assertion is one item on your checklist for a healthy response. If an item fails, the check is down, and you see which item failed.

Type, operator and value#

Each assertion has three parts:

• Type (type in the API): what to look at, such as status_code or body.
• Operator (op in the API): how to compare, such as eq (equals) or contains.
• Value (value in the API): what you expect, such as 200.

Numbers and text. Some types hold a number: status_code, response_time_ms, tls.days_until_expiry, redirect.count and security.score. Use eq, neq, gt or lt with them. contains and matches on a number always fail. The other types hold text. Use eq, neq, contains or matches with them.

• gt and lt are strict. "At least 75" is gt 74.
• For a number type, write a whole number, such as 200. Do not write 200.0 or add spaces. obsrvly saves such a value, but every check then fails with assertion status_code: invalid expected value "200.0".
• On text, gt and lt read both sides as numbers. If either side is not a number, the assertion fails.
• eq on text must match the whole value exactly. contains looks for a piece of the value.
• Upper and lower case matter. contains OK does not match ok.
• There is no "does not contain" operator.

The rules#

• Every assertion must pass. obsrvly checks them in order. The first one that fails makes the check down. Its message becomes the failure message.
• No assertions: any 2xx is up. A URL or API monitor with no assertions is up for any success (2xx) status. Any other status is down, with a message such as status 503.
• With assertions, only your assertions count. Once you add any assertion, obsrvly no longer checks the status code for you. A body assertion can pass on a page with status 500.
• A failed request is down first. A timeout, a connection error or a certificate error makes the check down before any assertion runs.
• Up to 50 assertions per monitor, and up to 50 per step of a multi-step API monitor.

Regular expressions#

The matches operator takes a regular expression (regex): a pattern that describes text. For example, ^ok$ means exactly ok. v[0-9]+ means v followed by one or more digits.

• A pattern matches anywhere in the value. Add ^ (start) and $ (end) to match the whole value.
• URL, API and multi-step API monitors use the RE2 style of regular expressions. Look-ahead and back-references are not supported. Most simple patterns work.
• A pattern can be up to 1,024 characters. A longer one is refused when you save: a matches pattern can be at most 1024 characters.
• obsrvly does not check that a pattern is valid when you save. A broken pattern makes every check fail, for example with assertion body matches "[0-9" failed. Test your pattern before you save it.
• If a pattern is too slow, the check fails with the pattern is too slow to run on a value of N KB; shorten it, or use contains.
• Browser monitors use JavaScript regular expressions.

Add assertions in the dashboard#

1. Open the monitor's create or edit page. Find the assertions section. Its note reads every assertion must pass.
2. Select + add assertion. A new row appears.
3. Pick the type, then the operator. Type the value in the value box.
4. Save the monitor.

• The type list shows, in order: status_code, body, header, response_time_ms, redirect.count, redirect.final_url, security.score, json_schema.
• A new URL or API monitor starts with one row: status_code eq 200. A new TCP monitor starts with response_time_ms lt 50. UDP monitors and new multi-step steps start empty.
• A row with an empty value is not saved. You see no warning.
• If you saved a type through the API that the list does not offer, such as json.status, it stays in its row. The dashboard keeps it when you save.
• If the value is wrong, saving fails with a message such as assertions[0]: .... The number is the row, counting from 0.

On the monitor page, Settings & technical details shows an Assertions row, such as status_code eq 200, or none. For a multi-step monitor, each step's assertions appear under Steps. When a check fails, the banner reads Monitor is down — last failure with the time, then the failure message.

Add assertions through the API#

Send assertions in the assertions list when you create a URL, API, TCP, UDP, DNS or browser monitor (see chapter 13). Each one has type, op and value. Write the value as text, even for numbers:

"assertions": [
  {"type": "status_code", "op": "ASSERTION_OP_EQ",
   "value": "200"},
  {"type": "body", "op": "ASSERTION_OP_CONTAINS",
   "value": "ok"}
]

• An UpdateMonitor with config replaces the whole config. Send every assertion you want to keep, not only the new one (3.7).
• On a multi-step API monitor, each step has its own assert list inside apiSteps. The top-level assertions list is ignored.
• An unknown type is refused when you save, with a list of the types you can use.

Multi-step API monitors#

Each step's assertions check that step's response only. The first step that fails stops the run. Its message starts with the step number, counting from 1, and the step name. For example: step 2 (login): assertion status_code == 200: got 401.