Core Concepts

Everything in pg_health_framework splits into two halves that are deliberately kept apart, linked only by an internal identifier called check_uid:

• The catalog — namespaces, categories, checks, and thresholds. This is metadata: what could be measured, and what a good or bad result looks like. It's long-lived and rarely changes — you set it up once, and a health-check run doesn't touch it.
• The suite and its runs — an ordered list of which checks to run together (a suite), and then the actual executions of that suite over time (runs), what each one collected, and how each check was judged. This is execution: which checks you actually chose to run together, and what happened when you did.

A suite doesn't know or care which namespace or category a check came from — it just holds an ordered list of checks. All 165 built-in checks live under one namespace, PGHF, and most sites never need to register a second one — see Using the Seed Catalog. If you do register your own checks later, they mix into any suite alongside the built-ins with nothing extra required — see Creating Your Own Checks and Thresholds.

The hierarchy — what belongs to what

Namespace                                 e.g. 'PGHF' (built-in), 'ACME' (yours)
    │
    └── Category                          scoped to one namespace, e.g. '01'
                │
                └── Check                 e.g. check ID 'PGHF01-006' / 'ACME01-001'
                            │              (the check ID is built automatically from
                            │               the namespace, category, and a run number)
                            │
                            ├── Threshold          0 or 1 default, plus 0 or more
                            │                      per-suite overrides
                            ├── Event               0 or more — optional notifications,
                            │                       fired on a severity change — see
                            │                       the Events book
                            └── Suite membership    0 or more — which suite(s) include
                                                     this check, and at what position

Suite ("check run")                       e.g. 'default', 'nightly'
    │
    └── Suite membership                  an ordered list of checks, drawn from
                                           any namespace/category, in any order

Run                                       one row per actual execution of a suite
    │
    ├── Raw results                       one row per check in that run — what was collected
    └── Evaluations                       one row per evaluated check — the judged severity

A check ID — like PGHF01-006 — is built automatically from three pieces: the namespace code (PGHF), the category code (01), and a zero-padded run number (006). You never type a check ID by hand when creating a check; it's computed for you and stays in sync automatically if the run number ever changes.

The process, in order

Using pg_health_framework, in the order things actually happen:

STAGE 1 — DEFINE THE CATALOG  (once; rarely changes)
  Register a namespace and category
  Register a check                     — its check ID is generated automatically
  Set a threshold                       — optional; only checks with a threshold (or a
                                           custom evaluator) get judged later
  Register an event                     — optional; a notification fired on a severity change

STAGE 2 — BUILD A SUITE  (once; edit anytime)
  Create a suite
  Add checks to it                      — from any namespace/category, in any order

STAGE 3 — RUN IT  (repeat on your own schedule — cron, an orchestrator, or by hand)
  Collect     ──► raw data, no judgment yet
  Evaluate    ──► raw data compared against thresholds ──► a severity
  Report      ──► read the results back out

Stage 1 is already done for you: pghf.seed_data(), a single function, runs it automatically at install time for the entire built-in catalog. You only work through Stage 1 yourself if you're registering something of your own — see Creating Your Own Checks and Thresholds.

The rest of this guide follows this same order: Using the Seed Catalog covers everything the automatic seeding already gives you — for most sites, that's the whole job. Extending it with your own checks comes later, and has its own dedicated book.

Continue to Architecture Overview.