Uptime monitors

Beta

Being rolled out. The interface described here is the one of the next release: it may still change, and may not be enabled on your tenant yet.

Monitoring is being rolled out: as long as it is not enabled on your tenant, sng apply rejects Monitor manifests.

A monitor checks at regular intervals that a public target responds: an HTTP(S) URL, a TCP port or a DNS server. Its state (Up, Down…) feeds your notifications and your status page.

Prerequisites

The sng CLI authenticated and a tenant session: sng tenant use acme.
The right to apply manifests (deploy:write, included in readwrite).
A target reachable from the Internet: private addresses and internal names are refused.

1. Create an HTTP monitor

sng monitor create api --http https://api.example.com/health --expect 200 --interval 5m

monitor "api" declared in tenant acme, first checks within a few minutes

The same monitor as a manifest:

infra/Monitor/api.yml
apiVersion: monitoring.stackngo.io/v1alpha1
kind: Monitor
metadata:
  name: api
spec:
  type: HTTP
  target: https://api.example.com/health
  interval: 5m
  http:
    expectedStatusCodes: [200]
  tls: {}                     # alert before the certificate expires (14 and 3 days)

sng apply infra/Monitor/api.yml

For an https:// URL, sng monitor create adds tls: {}: you are also warned before the certificate expires.

Interval and tier

The minimum interval depends on the tenant's tier: 5 minutes in 3XS, 2 minutes in 2XS, 1 minute from XS, 30 seconds from M. sng monitor create uses 5m by default, valid on every tier; an interval shorter than the tier minimum is refused (IntervalBelowTier). See Tiers and quotas.

2. The other check types

# TCP port
sng monitor create db --tcp db.example.com:5432 --interval 5m

# DNS server: queries ns1.example.com for the A record of example.com
sng monitor create resolver --dns ns1.example.com --query example.com --interval 5m

Type	`target`	Successful when
`HTTP`	`http://` or `https://` URL	2xx response (or a code from `expectedStatusCodes`), body matching `bodyMustContain` / `bodyMustNotContain`
`TCP`	`host:port`	the connection is established (and the TLS handshake if `tcp.tls: true`)
`DNS`	queried DNS server	the server responds to `dns.queryName` (type `dns.queryType`, `A` by default) with the expected code (`NOERROR` by default)
`ICMP`	host	ping — not available yet: refused with `NotSupported`

The options specific to each type (HTTP method, headers, redirects, IPv6…) are in the manifest reference (Monitor, see the reference).

3. Set the sensitivity

Setting	Flag	Default	Effect
`interval`	`--interval`	`5m` with `sng monitor create`, `1m` in a manifest	`30s`, `1m`, `2m`, `5m` or `10m`
`timeout`	`--timeout`	`10s`	maximum duration of a check, from `1s` to `30s`, less than `interval`
`failureThreshold`	`--threshold`	`3`	number of consecutive failures (1 to 5) before declaring the target down

With interval: 5m and failureThreshold: 3, an outage is detected after about 15 to 20 minutes. Lower the threshold to react faster, at the cost of false alerts on a one-off network incident.

4. Read a monitor's state

State	Meaning
`Pending`	monitor admitted, waiting for the first measurements
`Up`	checks succeed
`Down`	the target has been failing for `failureThreshold` checks
`Unknown`	no recent measurement, or monitor refused by the platform
`Paused`	monitor suspended (`paused: true`)

The state is visible on your status page ("opérationnel", "panne", "inconnu", "suspendu") and triggers notifications.

State in the CLI

In this version, sng monitor list and sng kind get Monitor api display the declared monitors, not yet their state or the reason for a refusal (sng kind get shows # status: not observed yet). To follow the state, publish a status page and connect a notification channel.

5. Suspend, modify, delete

spec:
  paused: true      # suspends checks without deleting the history

Modify the manifest then sng apply, or rerun sng monitor create with the new flags (the manifest is replaced). To delete:

sng monitor delete api

⚠ Suppression définitive du Monitor "api".
Tapez « oui » pour confirmer : oui
deleted: api

Verification

sng monitor list

The list displays each declared monitor (NAME) and the date of its last modification (UPDATED). Then, a few minutes later, the status page shows the monitor as "opérationnel".

Going further

Refused targets: private, loopback, link-local, CGNAT (100.64.0.0/10) addresses, names without a dot, and internal names (.local, .internal…). To monitor an App of the tenant, use its public URL (https://<service>-<app>.acme.dev.stackngo.app/).
Number of monitors: bounded by the tier (10 in 3XS, 25 in 2XS, 50 in XS…). Beyond that, the most recent monitors are refused (QuotaExceeded); the oldest ones continue.
Origin of checks: checks start from the gra region. The quorum field is planned for checks from several regions; it has no effect today.
HTTP headers: Host, Authorization, Cookie and a few others are refused, and header values are in clear text: never put a secret in them. Monitor a public health route instead.
History: it is kept outside the manifest; suspending a monitor does not erase it.
State change: the monitor switches to Down when its last failureThreshold checks have all failed, and returns to Up as soon as checks succeed again.

Common errors

Symptom	Cause	Fix
`sng apply` refuses: `type HTTP : target doit être une URL http(s)://`	URL without a scheme	`https://…`
`sng apply` refuses: `seul le type HTTP accepte une URL : TCP host:port, ICMP/DNS host`	URL given to a TCP or DNS check	`host:port` for TCP, hostname for DNS
`sng apply` refuses: `timeout doit être inférieur à interval`	`timeout: 30s` with `interval: 30s`	Lower `timeout`
`sng monitor create`: `exactly one of --http, --tcp or --dns is required`	No target, or several	A single target per monitor
Monitor "inconnu" on the status page well beyond a few minutes	Refused by the platform: interval below the tier minimum, internal target, ICMP, quota reached, unknown channel	Check these points; the reason for the refusal is not displayed by the CLI yet
Monitor `Down` while the service responds in the browser	Return code outside `expectedStatusCodes` (a followed 301 redirect ends up elsewhere), `bodyMustContain` text missing, IPv4 unavailable	Check the response with `curl -i`; adjust `expectedStatusCodes` or `ipFamily`

Prerequisites​

1. Create an HTTP monitor​

2. The other check types​

3. Set the sensitivity​

4. Read a monitor's state​

5. Suspend, modify, delete​

Verification​

Going further​

Common errors​

See also​