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

# Monitoring & Status Pages

> How B Brands observes every platform: one Better Stack monitoring layer, three environments, public status pages driven by real production health.

<Info>
  This section documents the **B Brands monitoring platform** — the single layer
  that watches every app and integration across `development`, `certification`
  and `production`, publishes a public status page per environment, and is
  defined entirely as code (Terraform) and operated through GitHub Actions.
</Info>

## What this is

Every environment has its own **Better Stack** workspace with a public status
page. Instead of a human deciding whether a component is healthy, the status is
derived from **real production traffic** flowing through `horizon-api`: the API
computes a health verdict per component, Better Stack polls it, and the status
page reflects reality automatically.

Two independent Better Stack products are used:

<CardGroup cols={2}>
  <Card title="Uptime" icon="heart-pulse">
    Status pages, HTTP monitors and cron heartbeats. Drives the green / yellow /
    red state each visitor sees.
  </Card>

  <Card title="Telemetry" icon="chart-line">
    Log sources, metrics and log-based alerts. Powers infrastructure charts and
    the (optional) per-service error-rate alerts.
  </Card>
</CardGroup>

## The three environments

Each environment is fully isolated: its own status page, its own monitors, its
own API host and its own tokens. Nothing is shared across environments.

| Environment   | Status page                       | Horizon API host               |
| ------------- | --------------------------------- | ------------------------------ |
| Development   | `development.status.bbrands.io`   | `development.api.bbrands.io`   |
| Certification | `certification.status.bbrands.io` | `certification.api.bbrands.io` |
| Production    | `status.bbrands.io`               | `api.bbrands.io`               |

## What each color means

The status page speaks to two audiences at once — the business (is the platform
usable?) and engineering (what exactly is failing?).

<CardGroup cols={3}>
  <Card title="Operational (green)" icon="circle-check">
    The component serves traffic normally. Error rate is within the healthy
    band.
  </Card>

  <Card title="Degraded (yellow)" icon="triangle-exclamation">
    The component still responds but a sustained error rate, a failing route or
    a stale cron was detected. Users may notice slowness or partial failures.
  </Card>

  <Card title="Down (red)" icon="circle-xmark">
    A real outage: the short-window error rate crossed the outage threshold. The
    component endpoint returns `503`.
  </Card>
</CardGroup>

## What is monitored

Every environment converges to the same catalogue, each pointing at its own
hosts.

<CardGroup cols={2}>
  <Card title="30 HTTP monitors" icon="globe">
    10 frontend apps + 11 API categories + 9 integrations. Better Stack polls
    each one every 1-3 minutes.
  </Card>

  <Card title="3 cron heartbeats" icon="clock">
    Health API, Health Integrations and Metrics Push. Confirm the scheduler
    itself keeps running.
  </Card>

  <Card title="4 status-page sections" icon="layer-group">
    Platforms, API, Integrations and Infrastructure — how components are grouped
    for visitors.
  </Card>

  <Card title="Telemetry sources" icon="database">
    One log/metrics source per environment for infrastructure charts and log
    alerts.
  </Card>
</CardGroup>

## How the signal flows

```mermaid theme={null}
flowchart LR
    subgraph app [horizon-api]
        traffic["Real traffic<br/>recordApiTraffic"]
        verdict["Tri-state verdict<br/>operational / degraded / down"]
        endpoint["GET /health/component/..."]
        crons["Health & metrics crons"]
    end
    subgraph bs [Better Stack]
        monitors["30 HTTP monitors"]
        reports["Status Reports API"]
        heartbeats["3 cron heartbeats"]
        telemetry["Telemetry source"]
        page["Status page"]
    end

    traffic --> verdict --> endpoint
    monitors -->|"pull every 1-3 min"| endpoint
    crons -->|"push create/resolve"| reports
    crons -->|"self-heartbeat"| heartbeats
    crons -->|"push latency metrics"| telemetry
    monitors --> page
    reports --> page
```

## The golden rule: monitors decide red, Status Reports decide yellow

This is the single most important concept for the whole platform. The two
health layers are deliberately independent so that a scheduler problem can never
fake an outage.

<CardGroup cols={2}>
  <Card title="Red (down) — HTTP monitors" icon="circle-xmark">
    A monitor polls the component endpoint. It only sees `503` when the
    short-window error rate is a real outage. This path has **no dependency on
    the cron scheduler**, so a missed tick cannot produce a false red.
  </Card>

  <Card title="Yellow (degraded) — Status Reports" icon="triangle-exclamation">
    The health crons compare each verdict against the published state and
    create/resolve Status Reports. A missed tick only **delays** the yellow
    transition, which is harmless.
  </Card>
</CardGroup>

## Where to go next

<CardGroup cols={2}>
  <Card title="Health Architecture" icon="sitemap" href="/monitoring/architecture">
    How the tri-state verdict is computed and published.
  </Card>

  <Card title="Infrastructure as Code" icon="cubes" href="/monitoring/terraform">
    The Terraform definition of every Better Stack resource, and `plan` vs
    `apply`.
  </Card>

  <Card title="CI/CD for Monitoring" icon="robot" href="/monitoring/github-actions">
    The GitHub Actions workflow that validates and applies changes safely.
  </Card>

  <Card title="Operations Runbook" icon="book" href="/monitoring/runbook">
    Day-2 tasks: sync env vars, add a monitor, rotate tokens, resolve drift.
  </Card>
</CardGroup>