Metrics and service tokens
Bridge serves two read-only endpoints for monitoring:
| Endpoint | What it reports |
|---|---|
GET /api/stats | Aggregate session statistics, derived from the recordings on disk. |
GET /api/cluster | Live topology: roles, worker health, the leader lease, and a count of active sessions. |
/api/stats is what the Admin console’s Overview tab reads. /api/cluster
answers the question a monitoring system actually asks about a cluster: are the
workers there, are they healthy, and is anything draining.
A service token is a named, read-only credential for that endpoint and nothing else. Use one instead of the cluster token. The cluster token provides an additional peer credential and grants no public administrative access. Service tokens provide independently revocable monitoring access.
Create a service token
- Open the Admin console from the floating button in the web interface.
- Go to API Tokens > Service tokens. In versions before v3.0.2, open the Service Tokens tab.
- Enter a name that says which system will use it, such as
prometheus. - Select Create.
- Select Copy token in the dialog and save the token in your monitoring system’s secret store.
- Select Done.
If automatic copying fails, select the token text and copy it manually. Bridge stores only a hash of the token. Closing the dialog with Done, Escape, or the admin panel clears the displayed value. If you close it before copying, revoke the token and create another.
Scrape the endpoint
Send the token in the X-Bridge-Service-Token header:
curl -H "X-Bridge-Service-Token: $TOKEN" https://bridge.example.com/api/statsFor Prometheus, request the text exposition format. Both endpoints support it:
curl -H "X-Bridge-Service-Token: $TOKEN" \
"https://bridge.example.com/api/stats?format=prometheus"
curl -H "X-Bridge-Service-Token: $TOKEN" \
"https://bridge.example.com/api/cluster?format=prometheus"What the cluster endpoint reports
The gauges from /api/cluster?format=prometheus:
| Series | Meaning |
|---|---|
bridge_cluster_workers | Registered session and proxy workers. |
bridge_cluster_workers_healthy | Workers whose last heartbeat is inside the staleness window. |
bridge_cluster_workers_draining | Workers draining before they exit. |
bridge_cluster_active_sessions | Active sessions, over the scope named by the scope label. |
bridge_cluster_leader_held | 1 when a control-plane leader lease is held and unexpired. |
bridge_cluster_worker_active | Sessions each worker reports serving, labelled by worker and role. |
bridge_cluster_worker_max_concurrent | Sessions each worker accepts at once, same labels. |
Alert on bridge_cluster_workers_healthy falling below what the orchestrator is
configured to keep, and on bridge_cluster_leader_held reaching 0 for longer
than the lease duration. Compare bridge_cluster_worker_active against
bridge_cluster_worker_max_concurrent to see saturation rather than infer it.
Read the scope label on bridge_cluster_active_sessions. It is cluster
when the count came from the shared registry and covers every node, and
instance when it covers only the process that answered. Behind a load balancer
an instance count depends on which replica served the scrape and moves between
scrapes for that reason alone. Bridge labels it rather than hiding it, so a
dashboard cannot quietly present a per-process number as a fleet-wide one.
The token works in the header only. Passing it as a query parameter does not authenticate. An edge proxy logs full request URIs, so a token in the URL would be written to its access logs in cleartext.
What a service token cannot do
A service token reaches counts and topology. Neither endpoint returns session identifiers, user names, target hosts, client addresses, or recordings.
That is why /api/cluster exists as its own endpoint rather than as a wider
permission on the Admin console’s cluster view. The console’s version of the same
screen lists every active session with the user and the target it reaches, which
is the one thing a scraping credential must never hold. /api/cluster reports the
same infrastructure and a count. The admin endpoint stays admin-only.
A service token also cannot create another service token. Minting one is an administrative operation, so a leaked scraping credential cannot widen its own access.
Rotate a token
Create the replacement first, move the monitoring system onto it, then revoke the old one.
Bridge allows one live token per name, so rotating in that order lets you keep the name. Revoking first and then creating also works. Creating a second token under a name already in use is refused, and the message says to revoke the existing one or choose another name.
Revoke a token
- Open Admin > API Tokens > Service tokens.
- Select Revoke beside the token.
The revocation applies on the next request, across every node in the deployment. Bridge verifies a presented token against the datastore rather than against a copy loaded at startup, so nothing needs restarting.
A revoked token stays in the list, marked, so the record shows that a credential was withdrawn and when.
The per-process session count is absent from /api/stats output
/api/stats omits an active-session gauge. The count it holds is in-memory state
for one process, so behind a load balancer it would report whichever replica
answered and jump between scrapes.
/api/cluster answers this properly instead: it reads the shared registry when
one is available, which makes the count fleet-wide, and labels the result with its
scope either way so you can tell.