# Reading relay health

> How the Relays screen derives live, idle, and offline for each QUIC edge, how telemetry is attributed by SNI, and what these signals cannot tell you.

The Relays screen shows the QUIC relay edge fleet that carries netcode
traffic for the `arena` namespace. It is deliberately a thin read over
two real signals: whether each edge's hostname **resolves in DNS**, and
whether **QUIC telemetry attributed to that edge is fresh**. Nothing on
the screen is synthesised. Before any sessions route through an edge,
the row is expected to read `idle` with `—` in every metric column.

The edge list itself comes from infrastructure configuration (for
example `relay-us`, `relay-uk`), not from discovery. An edge that has
never come up still appears in the table.

## What the three statuses mean

| Status | Chip tone | Derivation |
| --- | --- | --- |
| `live` | ok (green) | The hostname resolves **and** QUIC telemetry attributed to this edge fell inside the liveness window. |
| `idle` | warn (amber) | The hostname resolves, but no telemetry was attributed to this edge inside the window. |
| `offline` | bad (red) | The hostname does not resolve. The endpoint cell shows `no DNS` in place of an IP. |

Any status the screen does not recognise renders as `offline`.

The KPI strip summarises the same three states:

| KPI | Meaning |
| --- | --- |
| **Edges** | Number of edges in the configured fleet. |
| **Resolving** | Edges whose status is not `offline`, over the fleet size. That is, DNS answered. |
| **Live** | Edges whose status is `healthy` (`live`), over the fleet size. That is, telemetry is fresh. |
| **Window** | The liveness window, in minutes. |

`Resolving` counts both `live` and `idle` edges. An edge can be
resolving and still be carrying nothing.

## How an edge is identified: DNS and SNI attribution

Each row carries two identifiers, and they are checked separately:

| Column | Field | What it is |
| --- | --- | --- |
| Edge | `id`, `label` | The infra-side edge id and its human label. |
| Endpoint | `url` | The configured relay endpoint for that edge. |
| Endpoint (second line) | `ip` | The address DNS returned, or `no DNS` when resolution failed. |

Telemetry is attributed to an edge by **SNI**. Samples of type
`quic_transport_sample` carry the server name the client presented on
the QUIC/TLS handshake, and the screen matches that name against the
edge's endpoint. This is why the endpoint hostname is the identity that
matters, not the IP: if clients dial an edge under a different server
name than the one configured here, the samples do not land on this row,
and the edge reads `idle` even while it is passing traffic.

## The liveness window and why metrics read as a dash

The liveness window is the lookback period used to decide whether
telemetry counts as fresh. It is returned by the API as `freshSecs` and
displayed in the KPI strip in minutes. When the response does not carry
`freshSecs`, the console falls back to 600 seconds (10 minutes). Always
read the window off the KPI strip rather than assuming a value — it is a
server-side setting.

The per-edge metric columns are populated from the same attributed
samples, so they are empty for exactly as long as the edge is not
`live`:

| Column | Field | Rendered as |
| --- | --- | --- |
| Last telemetry | `lastSeen` | Local wall-clock time of the most recent attributed sample, otherwise `—`. |
| RTT | `rtt` | Milliseconds, otherwise `—`. |
| Peers | `peers` | Count, otherwise `—`. |
| Egress | `egress` | Gigabytes, otherwise `—`. |

A `—` is the absence of a sample, not a zero. Do not read `—` in the
Peers column as "zero peers connected"; read it as "no sample has been
attributed to this edge inside the window".

The fleet table refreshes every 30 seconds, and the header shows the
relative age of the last successful fetch next to a manual **Refresh**
button. While the first fetch is in flight the panel reads
`Probing edges…`; if the infra list is empty it reads
`No edges configured.`

## Attached but not flowing: what these signals do not tell you

This is the gap the screen is explicit about. DNS resolvability and
telemetry freshness answer two questions:

1. Can a client find this edge?
2. Has this edge reported a QUIC transport sample recently?

Neither one answers whether **objects are moving** through the
namespace. A relay can accept a QUIC connection, complete the handshake,
emit transport samples, and therefore read `live` — while no publisher
is producing and no subscriber is receiving on `arena`. An edge that is
attached but not flowing is indistinguishable, on this screen, from an
edge that is carrying a full session load, except by the magnitude of
the Peers and Egress columns.

Alongside the fleet query, the screen polls
`observability.relayHealth` for the `arena` namespace on a 5 second
interval. That procedure calls the `relay.metrics` service RPC with a
3 second timeout and returns the raw metrics text:

| Response field | Meaning |
| --- | --- |
| `configured: true`, `text` | The relay returned its metrics text. |
| `configured: false`, `text: ""` | The RPC failed or timed out. |

The short timeout is intentional: the query polls frequently, so a slow
engine must read as "No data" on a single tick rather than queue up
requests. Note also what `configured: false` means — the RPC did not
complete. That is an operations problem on the path to the metrics
service, not evidence that the relay is down. The panel reports "No
data" rather than attributing the failure to the relay.

## Triage: an edge that will not resolve

The edge shows `offline`, and the endpoint cell shows `no DNS` instead
of an IP.

- Resolve the hostname in the **Endpoint** cell yourself. The screen is
  reporting a DNS answer, or the lack of one, for exactly that name.
- Confirm the endpoint recorded in infra is the name you expect. The row
  is rendered from configuration; a typo in the configured URL produces
  a permanent `offline` for an edge that is running fine.
- Until DNS answers, no telemetry can be attributed to this edge, so the
  Last telemetry, RTT, Peers and Egress columns will stay `—` regardless
  of what the relay process is doing.

An edge in this state has never been ruled out as healthy — it has only
been ruled out as *reachable by name*.

## Triage: an edge that resolves but stays idle

The edge shows `idle`: DNS answered, but nothing was attributed inside
the liveness window.

Work through the causes in order of how common they are:

1. **No traffic has been routed there yet.** This is the expected
   steady state for a fleet that is provisioned but not yet serving
   sessions. Every edge reads `idle` with `—` metrics until sessions
   route through one.
2. **Traffic is going to a different edge.** Check the other rows. If
   one edge is `live` and the rest are `idle`, routing is concentrating
   sessions rather than the fleet being broken.
3. **SNI mismatch.** Clients may be reaching the relay under a server
   name that does not match the configured endpoint, so
   `quic_transport_sample` records do not attribute to this row. Compare
   the server name clients present on the handshake with the **Endpoint**
   hostname.
4. **The telemetry path, not the relay.** If no edge in the fleet has a
   `Last telemetry` value and the relay metrics panel also reports no
   data, suspect sample ingestion or the `relay.metrics` RPC rather than
   the edges themselves.

An `idle` edge is not an error state and FirstByte does not treat it
as one. It means the screen has no evidence either way about whether
that edge is carrying traffic.

## Related

- [Telemetry](/platform/telemetry) — the metric and trace streams the gateway emits
- [Authentication](/concepts/authentication) — relay tokens and the `namespace_auth` hook that gates publish/subscribe