# Metrics (/docs/reference/metrics)

> The 47 Prometheus metric families better-compute exposes on /metrics, with their labels.



Every family carries the `better_compute_` prefix and none has a tenant label (series stay bounded by `maxSeries`). Histograms also expose `_bucket`, `_sum` and `_count` series. Families are grouped by the function that registers them: `standardMetrics` on every process, the others where a host wires them.

## standardMetrics [#standardmetrics]

| Metric                                      | Type      | Labels          | Description                                                                                                                                                                                 |
| ------------------------------------------- | --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `better_compute_gateway_sessions`           | gauge     | `role`          | Open daemon sessions on this gateway                                                                                                                                                        |
| `better_compute_gateway_handshakes_total`   | counter   | `outcome`       | Session handshakes                                                                                                                                                                          |
| `better_compute_command_latency_seconds`    | histogram | `kind`, `lane`  | Command enqueue to terminal result. Buckets (s): 0.05, 0.1, 0.25, 0.5, 1, 1.5, 2.5, 5, 10, 30, 60                                                                                           |
| `better_compute_commands_swept_total`       | counter   | `to`            | Commands the CommandSweeper moved                                                                                                                                                           |
| `better_compute_work_queue_depth`           | gauge     | `kind`          | Due work\_queue rows                                                                                                                                                                        |
| `better_compute_reconcile_duration_seconds` | histogram | `reconciler`    | One reconciler run. Buckets (s): 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30                                                                                                |
| `better_compute_generation_lag_nodes`       | gauge     |                 | Nodes whose observed generation is behind                                                                                                                                                   |
| `better_compute_placements_total`           | counter   | `outcome`       | Placement attempts                                                                                                                                                                          |
| `better_compute_booking_conflicts_total`    | counter   |                 | Booking conflicts that forced a replan                                                                                                                                                      |
| `better_compute_pool_gpus`                  | gauge     | `state`         | GPUs by state across pools                                                                                                                                                                  |
| `better_compute_node_connectivity`          | gauge     | `state`         | Nodes by connectivity                                                                                                                                                                       |
| `better_compute_backlog`                    | gauge     | `queue`         | Rows waiting in a queue table                                                                                                                                                               |
| `better_compute_usage_dead_letters_total`   | counter   |                 | Usage events dead-lettered                                                                                                                                                                  |
| `better_compute_iam_inbox_spill_total`      | counter   |                 | IAM events spilled because the inbox was down                                                                                                                                               |
| `better_compute_iam_calls_total`            | counter   | `op`, `outcome` | IamPort calls                                                                                                                                                                               |
| `better_compute_iam_call_duration_seconds`  | histogram | `op`            | IamPort call latency (each op takes ≥1 IAM lock acquisition). Buckets (s): 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30                                                      |
| `better_compute_resolver_lookups_total`     | counter   | `result`        | Authz resolver lookups                                                                                                                                                                      |
| `better_compute_tenant_states`              | gauge     | `state`         | IAM tenants compute refuses (§12.8), by state: suspended, deleted                                                                                                                           |
| `better_compute_tenant_teardowns_pending`   | gauge     |                 | Deleted tenants whose teardown has not finished (a module still releasing)                                                                                                                  |
| `better_compute_sandbox_ready_seconds`      | histogram | `source`        | Sandbox create to its instance first running (§3.7), by source: a warm claim or a cold create; the counts give the warm-pool hit ratio. Buckets (s): 0.5, 1, 2, 5, 10, 20, 30, 60, 120, 300 |
| `better_compute_sandbox_expiry_lag_seconds` | histogram |                 | How late a sandbox was expired after its expiresAt. Buckets (s): 1, 5, 15, 30, 60, 120, 300, 900                                                                                            |
| `better_compute_sandbox_warm_instances`     | gauge     | `state`         | Unclaimed warm-pool instances, by instance state                                                                                                                                            |
| `better_compute_sandbox_warm_deficit`       | gauge     |                 | Warm instances missing below the templates’ warm.min, summed over live templates                                                                                                            |
| `better_compute_sandbox_warm_refills_total` | counter   |                 | Warm-pool instances created to refill templates                                                                                                                                             |
| `better_compute_cert_expiry_seconds`        | gauge     | `kind`          | Seconds until the soonest expiry                                                                                                                                                            |
| `better_compute_clock_offset_seconds`       | gauge     |                 | Process clock minus compute\_now()                                                                                                                                                          |
| `better_compute_security_events_total`      | counter   | `type`          | Security events recorded                                                                                                                                                                    |

## createObserver [#createobserver]

| Metric                                 | Type      | Labels                            | Description                                                                                                |
| -------------------------------------- | --------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `better_compute_spans_total`           | counter   | `kind`, `name`, `outcome`, `code` | Units of work by kind, name, outcome and code                                                              |
| `better_compute_span_duration_seconds` | histogram | `kind`                            | Latency of units of work by kind. Buckets (s): 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30 |

## meteredAttestor [#meteredattestor]

| Metric                                         | Type      | Labels                | Description                                                                                          |
| ---------------------------------------------- | --------- | --------------------- | ---------------------------------------------------------------------------------------------------- |
| `better_compute_attestor_verifications_total`  | counter   | `attestor`, `outcome` | Attestor verifications by outcome                                                                    |
| `better_compute_attestor_verification_seconds` | histogram | `attestor`            | Attestor verification time. Buckets (s): 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30 |

## meteredGatewayServices [#meteredgatewayservices]

| Metric                                       | Type      | Labels              | Description                                                                                           |
| -------------------------------------------- | --------- | ------------------- | ----------------------------------------------------------------------------------------------------- |
| `better_compute_gateway_service_calls_total` | counter   | `method`, `outcome` | Join, Renew and Secret calls by outcome                                                               |
| `better_compute_gateway_service_seconds`     | histogram | `method`            | Join, Renew and Secret time. Buckets (s): 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30 |

## meteredProvider [#meteredprovider]

| Metric                                 | Type      | Labels                          | Description                                                                      |
| -------------------------------------- | --------- | ------------------------------- | -------------------------------------------------------------------------------- |
| `better_compute_provider_calls_total`  | counter   | `provider`, `method`, `outcome` | Provider API calls by outcome                                                    |
| `better_compute_provider_call_seconds` | histogram | `provider`, `method`            | Provider API call time. Buckets (s): 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60 |

## placementObserver [#placementobserver]

| Metric                             | Type      | Labels   | Description                                                                                                |
| ---------------------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `better_compute_placement_seconds` | histogram | `placer` | One placement attempt, by placer. Buckets (s): 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30 |

## gatewayCollector [#gatewaycollector]

| Metric                                             | Type  | Labels            | Description                                                                    |
| -------------------------------------------------- | ----- | ----------------- | ------------------------------------------------------------------------------ |
| `better_compute_gateway_open_sessions`             | gauge | `gateway`, `role` | Open agent sessions by role                                                    |
| `better_compute_gateway_stream_headroom`           | gauge | `gateway`         | Streams this gateway can still admit                                           |
| `better_compute_gateway_draining`                  | gauge | `gateway`         | Whether the gateway is draining (1) or not (0)                                 |
| `better_compute_gateway_lease_held`                | gauge | `gateway`         | Whether the gateway holds its lease (1) or is fenced (0)                       |
| `better_compute_gateway_commands_in_flight`        | gauge | `gateway`         | Commands dispatched and not yet settled                                        |
| `better_compute_gateway_sessions_upgrade_required` | gauge | `gateway`         | Sessions told to upgrade                                                       |
| `better_compute_gateway_loop_consecutive_failures` | gauge | `gateway`, `loop` | Failed runs of a gateway loop since its last clean one (alert on a stuck loop) |
| `better_compute_gateway_loop_failures`             | gauge | `gateway`, `loop` | Failed runs of a gateway loop since start                                      |
| `better_compute_gateway_loop_last_ok_age_seconds`  | gauge | `gateway`, `loop` | Seconds since a gateway loop last ran cleanly (-1 before its first clean run)  |

## revocationFeedCollector [#revocationfeedcollector]

| Metric                                                | Type  | Labels | Description                                                                                    |
| ----------------------------------------------------- | ----- | ------ | ---------------------------------------------------------------------------------------------- |
| `better_compute_revocation_feed_consecutive_failures` | gauge | `feed` | Revocation feed polls failed in a row: revoked certificates keep their sessions while it fails |

## eventCounter [#eventcounter]

| Metric                        | Type    | Labels             | Description                     |
| ----------------------------- | ------- | ------------------ | ------------------------------- |
| `better_compute_events_total` | counter | `family`, `module` | Outbox events by catalog family |
