# Runbooks for Alerts and Error Codes

> A runbook for every Helm chart alert, problem code, OAuth error code and operator failure reason: what it means, who it affects, and how to diagnose and fix it.

Every alert nauthera-server's Helm chart raises, and every error code the server or its
operator answers with, has a runbook. Each one says:

| Section | What it answers |
|---|---|
| **Meaning** | What happened, and every cause that leads to it |
| **Impact** | Who is affected and how badly: users signing in, relying parties, administrators, auditors |
| **Diagnosis** | Steps to find which cause it is, with the commands, queries, log keys and audit records to read |
| **Mitigation** | What to do about each cause, for each audience |
| **Escalation** | When it is not expected, who to involve, and what to attach to an issue |

| Catalog | Reached from |
|---|---|
| [Alerts](https://www.nauthera.io/docs/v1/runbooks/alerts) | The `runbook_url` annotation of every alert in the chart's PrometheusRule, the operator's group included |
| [Problem codes](https://www.nauthera.io/docs/v1/runbooks/problems) | The `type` of an RFC 9457 problem response, `https://nauthera.io/problems/<code>` |
| [OAuth errors](https://www.nauthera.io/docs/v1/runbooks/oauth) | The `error_uri` of an OAuth error response or authorization error redirect |
| [Operator failure reasons](https://www.nauthera.io/docs/v1/runbooks/operator) | The reason on a resource's `Ready` condition, as `kubectl describe` shows it |

## Where the links point

The links that alerts and responses carry are stable and do not name a docs version:

| URL | Redirects to |
|---|---|
| `https://nauthera.io/problems/<code>` | `/docs/<latest>/runbooks/problems/<code>` |
| `https://nauthera.io/runbooks/<catalog>/<name>` | `/docs/<latest>/runbooks/<catalog>/<name>` |

A problem's `type` is its identifier (RFC 9457 §3.1.1) as well as a link, so branch on
`code` or `type`, never on the text of the page. A client should not fetch the URL on its
own; it is for the developer reading the response.

To link alerts to runbooks of your own instead, set the chart's
`metrics.prometheusRule.runbookUrl`: each alert then links to `<runbookUrl>/<alert name>`.
An empty value leaves the annotation out. See [Observability](https://www.nauthera.io/docs/v1/observability).

## Offline

The server binary carries the runbooks of its own version:

```bash
nauthera-server runbook                              # list every runbook
nauthera-server runbook alerts NautheraServerDown    # print one
nauthera-server runbook problems invalid_credentials
nauthera-server runbook oauth invalid_grant
```

The operator's failure reasons are not in the server binary; read them here.

## Where they come from

The runbooks are declared in nauthera-server's source, beside the code that raises what
they describe (`internal/runbook` and `operator/internal/runbook`), and this site renders
them at build time. A change that adds or changes an alert, a code or a reason changes its
runbook in the same pull request, and the server's tests fail on one without a runbook.