HTTP monitors

Checking a URL over HTTP or HTTPS, including the keyword and content assertion.

Purpose

An HTTP monitor checks that a URL answers over HTTP or HTTPS: that a connection completes, that the response carries the status code you expect, and — optionally — that its body contains, or does not contain, a specific piece of text. It is the monitor type for a web application, an API endpoint, or anything else that speaks HTTP.

Use cases

• A public web page or marketing site that should return 200.
• An API health endpoint that should return 200 with a body that contains "ok".
• A page that should redirect, checked with http_follow_redirects off so the monitor sees the redirect's own status rather than where it leads.
• A page that must not show a maintenance banner — checked with a not_contains assertion against the banner's own text.

Configuration

Required:

• Target — a URL whose scheme is http or https and which names a host. A target with no scheme, no host, or any other scheme is refused.
• Method — GET or HEAD. No other method is accepted.
• Interval and timeout — see Concepts: states for the shared timing rules every monitor type follows.

Optional:

• Expected status — any value from 100 through 599. The probe compares the response's actual status code against this value.
• Follow redirects and verify TLS — whether the probe follows a 3xx response to its Location, and whether it validates the certificate chain on an https:// target.
• Content assertion — keyword, checked against the response body under keyword_mode.

The content assertion

An HTTP monitor may additionally check the response body. The mode is one of three values:

An unstated mode is read as none — the pre-assertion behavior, so a monitor written before this feature existed still means what it always meant.

The keyword is bounded at 1024 characters, matched as an exact, case-sensitive byte substring over the first 64 KiB of the response body. It is not a regular expression and it does not fold case, so this is the whole of what an HTTP monitor can assert about a body.

A content assertion cannot be configured against a HEAD method — a HEAD response carries no body, so contains could never hold and not_contains would hold vacuously either way, which is not a check you can learn anything from. An assertion with a mode other than none also requires a non-blank keyword.

Validation

• The target must parse as a URL with http or https as its scheme and a non-empty host.
• The method must be GET or HEAD.
• The expected status must be between 100 and 599.
• The keyword must be 1024 characters or fewer, and, for contains or not_contains, non-blank and paired with a method that returns a body.

Any other shape is refused rather than stored.

Probe behavior

The probe requests the target with the configured method, following redirects when that option is set and validating the certificate chain when TLS verification is set, and reads up to the first 64 KiB of the response body if a content assertion is configured. It compares the response's status code to the expected status, then evaluates the content assertion if one is configured.

Success

The check is UP when the response's status code equals the expected status, and — if a content assertion is configured — the assertion holds against the bounded body prefix.

Failure

A failed HTTP check states one of these causes:

A contains keyword that appears only past the 64 KiB prefix is keyword_not_found, the same cause as a keyword that is not in the body at all — the probe reads only the bounded prefix and never distinguishes "not in what we read" from "not present."

An HTTP check's network cause is deliberately coarse: the underlying HTTP client call that resolves the host, opens the connection, and completes any TLS handshake reports one error for any failure along that path, and the probe passes it through as network rather than inspecting it for a more specific reason. A TCP monitor or TLS monitor against the same host and port distinguishes DNS, connection, and TLS handshake failures from one another; an HTTP monitor does not.

Evidence

Every check result records the status code observed, the cause if it failed, and the latency of the request. A content assertion's result is carried in the cause, not as separate evidence, so an incident and a history row both say exactly why the check disagreed with what was expected.

Latency interpretation

Latency is the time from the start of the request to the last byte of the response the probe read — for a check with a content assertion, that includes however much of the body the assertion needed. A slow assertion target can therefore show higher latency than the same endpoint checked with keyword_mode: none, which is expected rather than a regression in the target itself.

Consensus interaction

An HTTP monitor's states, and how its assigned nodes' observations become one published state, follow the same rules every monitor type does — see Concepts: consensus and Concepts: states.

Common mistakes

• Configuring a content assertion against a HEAD method — refused at creation, not silently ignored.
• Expecting a 3xx status while http_follow_redirects is on — the probe follows the redirect, so the status it evaluates is the final response's, not the redirect's.
• Assuming contains/not_contains is case-insensitive or a pattern language — it is neither; it is an exact byte substring.

Troubleshooting

• Result is always unexpected_status — confirm the expected status against what the endpoint actually returns under normal operation; a redirect target commonly needs either http_follow_redirects on or the redirect's own status as the expected value.
• Result is network and the target is https:// — the cause does not say whether the failure was DNS, the connection, or the TLS handshake; point a TCP monitor or TLS monitor at the same host and port to see which one it is, or see TLS monitors if the goal is specifically to track certificate expiry.
• Result is keyword_not_found intermittently — the target may render the keyword only after content later than the 64 KiB prefix a check reads; the assertion is bounded on purpose and does not grow to chase a page's size.

Security and network considerations

The probe runs from the nodes assigned to the monitor, so it connects to the target from wherever those nodes are — the same network exposure any client at that node's location would have. Verifying TLS is on by default; turning it off should be a deliberate choice for a target whose certificate this deployment intentionally does not validate, not a way to make an otherwise unrelated failure go away.

Example

target: https://example.com/health
method: GET
expected_status: 200
keyword_mode: contains
keyword: "ok"
interval_seconds: 60
timeout_seconds: 10

Related concepts

• TLS monitors — for tracking certificate expiry specifically, rather than as a side effect of an HTTP check.
• Concepts: states
• Concepts: coverage

This article is part of this repository and is served by the same binary, so what you read here is the documentation for the version you are running.