Skip to main content

Core Concepts

Snitcher is built from a few composable building blocks.

Targets (Resources)​

A Resource (target) is one thing you want to watch. Every resource has a check type plus common settings: interval, timeout, retries, IP version, and an optional inverted mode (swap Up/Down — useful for a firewalled port that should not be reachable).

Check types:

  • HTTP / HTTPS — expected status codes or a min/max range; keyword and JSON-path assertions; custom headers, body, and Basic/Bearer auth; redirect handling; TLS certificate capture with cert-expiry alerts; a degraded-latency threshold.
  • TCP — connect checks with optional TLS/STARTTLS and send/expect patterns.
  • ICMP — ping with configurable packet count, size, and TTL, plus a loss threshold.

Status model​

Each check result is Up, Down, or Degraded. The server derives a resource's overall status across all online Scouts:

  • All online Scouts Down → Down, unless a down-confirmations quorum is set and not yet met (see Targets) — then it reads Degraded.
  • A mix of Down and Up → Degraded (partial outage).
  • Any Degraded (no Down) → Degraded.
  • All Up → Up; nothing reported yet → Unknown.

A crashed Scout's stale result stops counting, so it can't wedge a resource's status forever.

Availability & uptime %​

The instantaneous status above is fixed, but how the Degraded and Unknown buckets feed uptime percentages is operator-configurable under Settings → Availability:

  • Count Degraded as Up (default on) — Degraded intervals count toward uptime rather than against it.
  • Count Unknown as Up (default on) — Unknown intervals (a data gap where no Scout could answer) count toward uptime rather than against it.

With both on (the default), only real Down lowers a target's uptime %. Turn either off to treat Degraded and/or Unknown as downtime in every uptime % and history-bucket calculation. The setting is app-wide and applies retroactively to how existing history is scored.

Scouts​

An Scout is a probe agent. It dials out to the server, receives its assigned checks, runs them, and reports results. Scouts surface online/offline, last seen, version, location, and clock skew. See Scouts & provisioning for enrolment, the config-driven first Scout, and key-based authentication.

Labels​

A Label is a freeform tag you attach to a target. There's no separate grouping entity — labels do triple duty: scoping a permission group to only the targets it should manage, filtering the audit log, and grouping targets in the UI. See Targets.

Alerting​

Alerting has three distinct concepts so it can grow without special cases:

  • Alerters — the channels notifications go out through: Email, Webhook, Slack, Discord.
  • Alert types — what can be alerted on: resource down/recovered/degraded, Scout down/up, cert-expiring, clock-skew, key-rotation-failed, Scout-untrusted, and incident events.
  • Alert rules — tie an alert type to an alerter, scope it (a specific resource, or leave it unscoped for global/system-level types), and set thresholds. See Alerting.

Users, groups & permissions​

Snitcher enforces a central permission set. Every guarded action requires a permission, granted via DB-driven groups a user belongs to. Users come from the built-in local admin or from OIDC/SSO (Keycloak), with group membership synced from the identity provider. See Users & Groups and SSO with OIDC.