> ## Documentation Index
> Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Health Page

> Monitor the operational health of your Soundcheck instance with a dashboard showing startup errors, configuration issues, integration status, and runtime metrics.

The Health page is an administrative dashboard that provides visibility into the operational health of your Soundcheck instance. It surfaces startup errors, configuration issues, integration status, and runtime metrics in a single view, helping you identify and resolve problems before they affect end users.

Access the Health page from the Soundcheck navigation at `/soundcheck/health`.

## Access Control

The Health page is gated by the `soundcheck.health.read` permission. Users without this permission will not see the page. No additional configuration is required — the page is available by default once the permission is granted.

## Summary Cards

The top of the page displays four summary cards computed from the sections below:

| Card                | Description                                                                                        |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| **Errors**          | Count of startup errors, configuration issues with Error severity, and integrations in Error state |
| **Warnings**        | Count of startup and configuration warnings, plus a warning if orphaned check results exist        |
| **Total Issues**    | Combined count of errors and warnings                                                              |
| **Integrations OK** | Number of integrations with Healthy status                                                         |

When issues are present, an action banner appears below the summary cards indicating that attention is needed.

## Sections

Each section loads independently and can be expanded to view details. Sections display a status badge (No Issues, Warning, or Error) in their header.

### Startup Errors

Issues encountered while loading configuration, plugins, and check definitions at startup. Each entry includes the severity (Error or Warning), message, source, and timestamp.

A clean startup shows "Soundcheck booted cleanly."

### Configuration Issues

Potential misconfigurations detected by analyzing the relationships between checks, tracks, and fact collectors. Issues are grouped by type, each with a resolution hint:

| Issue Type                   | What it Means                                                                        |
| ---------------------------- | ------------------------------------------------------------------------------------ |
| **Broken Fact Linkages**     | A check references a fact that no collector is configured to produce                 |
| **Orphaned Checks**          | A check exists but is not included in any track                                      |
| **Orphaned Integrations**    | An integration produces facts that no check references                               |
| **Conflicting Filters**      | A check and its parent track have entity filters that cannot match the same entities |
| **Invalid Liquid Templates** | A Liquid template in a check or collector configuration has syntax errors            |
| **Duplicate IDs**            | Two or more checks or tracks share the same ID                                       |

Each issue links to the relevant check, track, or integration detail page for quick navigation.

<Info>
  For large instances with many track/check combinations, the analysis may skip
  some checks. The section indicates when partial results are returned.
</Info>

### Integration Health

Health status of registered integrations (fact collectors) based on job queue activity. Each integration shows:

* **Status** — Healthy, Error, or Unknown
* **Last run** — when the integration last executed successfully
* **Last failure** — when the integration last encountered an error (if applicable)

Each entry links to the integration's detail page.

### Operational Stats

Job queue depth and check execution throughput. Counters reset on a configurable interval (default: 15 minutes).

Metrics shown:

* **Jobs in Queue** — number of queued jobs awaiting processing
* **Jobs Completed** — jobs completed since the last reset
* **Jobs Failed** — jobs that failed since the last reset (highlighted when above zero)
* **Checks Executed** — check evaluations completed since the last reset
* **Check Errors** — check evaluations that failed since the last reset (highlighted when above zero)
* **Last Check Execution** — timestamp of the most recent check evaluation
* **Last Check Failure** — timestamp of the most recent check failure

### Cache Health

Aggregation cache performance metrics. Counters reset on the same interval as Operational Stats.

* **Cache Hit Rate** — percentage of cache hits
* **Read Errors** — cache read failures (highlighted when above zero)
* **Write Errors** — cache write failures (highlighted when above zero)

### Database Cleanup

Check result records whose check IDs do not match any known check configuration. These are typically left over from deleted or renamed checks. The section displays a searchable table of orphaned check IDs with their latest result timestamp.

When orphaned results are found, contact your Soundcheck administrator to schedule a cleanup.