Metadata Columns Explained¶
Every registered check carries a set of classification metadata, set when the check is created or updated. None of this metadata makes a threshold decision by itself — it's what the evaluation layer (see How Threshold Evaluation Works) reads afterwards to interpret a check's collected value generically, without any per-check logic hardcoded anywhere.
| Field | Meaning |
|---|---|
| Internal ID | The check's real, permanent identity. Every other table that refers to a specific check points at this, never at the human-readable check ID below. |
| Namespace / category / run number | The three pieces a check ID is built from. The namespace (PGHF for built-ins, your own code for custom checks) and category are fixed forever once a check is created; the run number is the one piece you can still change later. The check ID itself — PGHF01-006-style — is computed automatically from these three, and recomputes the instant the run number changes. |
| Rationale | Required. Why this check exists — what it catches, why it matters, and what a database administrator should do about a bad result. |
| Result type | boolean, integer, numeric, text, or jsonb (PostgreSQL's structured, JSON-shaped data type) — the shape of the check's primary result. |
| Result unit | A free-text unit for numeric results — percent, bytes, seconds, count, and so on. |
| Boolean pass value | For a true/false check where one value clearly means "pass": which one. Left blank if the true/false result is purely informational, with no pass/fail meaning. |
| Numeric direction | For a number-based check with a clear better/worse direction: lower is better, higher is better, or a specific target value is the ideal. Left blank if there's genuinely no direction — for example, a raw setting where "better" depends entirely on your own workload. |
| Perfect value | An optional ideal value — for example, zero for an error count. |
| Description | An optional free-form technical note — portability caveats, anything the check needs supplied to it before it runs. This is distinct from the rationale above, which is required and answers "why does this matter," not "how does this work." |
The "value" convention¶
Every check whose result type isn't jsonb must record its primary number or answer under a key literally named "value", inside the structured data it returns when it successfully collects something. This is enforced centrally by the collection engine itself — a check that doesn't follow this fails loudly rather than silently producing data nothing downstream can read. Checks whose result type is jsonb (a structured breakdown is the whole point, with no single number that dominates) are exempt from this rule.
Percentage-of-a-ceiling checks¶
A raw count is often meaningless without knowing what it's being measured against — eight replication slots means something quite different on a server configured to allow ten versus one configured to allow a hundred. Where a natural ceiling exists, several checks compute a percentage as their "value" instead of the bare count: the number of replication slots in use against the maximum allowed, the worst slot's retained data against its configured limit (skipping cleanly rather than dividing by "unlimited" when that limit is turned off), and the proportion of login-capable roles that are superusers.
Not every count has a natural ceiling to divide by — the maximum number of connections a server allows, for instance, stays an absolute threshold because there's no "ceiling for a ceiling" to compare it against. The Adding Your Own Checks book has the full pattern and worked SQL examples, useful if you're writing your own checks and wondering whether a raw count or a percentage is the better choice.
Continue to How Threshold Evaluation Works.