Skip to content
bucker

Infrastructure

Explore, Infrastructure is a ledger of the machines, pods, containers, workloads, functions, platform services and datastores that have sent your project telemetry, and of how well each one is covered. It is not a map and not a dashboard of gauges: it answers "what do I have, what has gone quiet, what is not being collected, and what changed", and it says plainly what it does not measure.

An entity is created when a metric or log resource resolves to one (the precedence table in Infrastructure scope and OpenTelemetry decides which machine a resource is). Every point and log record then carries the entity's id.

The ledger

Section What it answers
Counts Entities by kind, provider and environment, largest first (ten groups, the rest folded into one).
Stale Entities whose metrics or logs have been silent for more than three of their expected intervals.
Coverage gaps Per signal (metrics, logs, events, traces): how many entities are missing, stale or unknown.
Not measured Saturation and provider incidents, each with the card that owes the answer. See below.
Changes Restarts, scaling, machine and cloud configuration, host events and collector changes recorded in the last 24 hours.
Entities One row per entity, most recently seen first, with a four-letter coverage code. Open a row for its detail.

The filters are closed: kind, provider and environment are picked from the values the digest counted, and coverage is a signal and a state (for example logs, missing). There is no free-text search. An infra saved view stores exactly those filters.

The coverage code

Four letters, in the order metrics, logs, events, traces: L live, Y lossy (sampled or thinned), S stale, M missing, U unknown. LSUU is "metrics live, logs stale, events and traces not decidable yet". The code is also spelled out for a screen reader, and it is never colour alone. Events and traces are unknown until error events and spans are attributed to entities; they are never missing, because Bucker cannot yet say they should be there.

One entity

The side sheet and infra_entity_get serve the same blocks:

Block Source Until its source ships
metrics The entity's own metric points over the last 60 minutes, per metric name (latest, min, max, average, points), and the service's request rate from the RED rollup when that pillar is on always answered; the RED line says why it is not measured when the pillar is off or the entity names no service
saturation INFRA-14 not_checked
changes Change events recorded against the entity, last 7 days always answered
issues Error events attributed to entities not_checked
coverage The entity's stored coverage, per signal, with the reason always answered
config Aliases and the declared, observed and inferred fields always answered

Not checked is not healthy

A block whose source card has not shipped answers not_checked, names that card, and is drawn as that sentence. It is never an empty list and never a zero, because either would read as "I looked and found nothing". A block that has a source and holds nothing says that in words (no points, no changes). Today saturation (INFRA-14), findings (INFRA-11), issues and provider incidents (INFRA-12, shown the moment any producer records one) are not_checked.

Names are the sender's text

Entity names, identities, providers, environments, services, releases, aliases, field keys and values, metric names and change summaries are chosen by whatever sent the telemetry. They are labelled untrusted in every response (trust.untrustedFields), shown in the dashboard as text and never as a link or markup, and, for an agent, a service principal or a person's OAuth client, passed through the infrastructure field policy first: credentials and Secret data are dropped or hashed, environment values are hashed, and injection-shaped text is redacted. See Scrubbing and privacy.

For agents

Two MCP reads: they need the infra:read scope (relation read_infra), which the telemetry:read tier does not grant, and the infra toolset. A token without it does not see them.

Tool Price What it returns
infra_fleet_digest 1,500 tokens (2,000 with entities) Counts, stale entities, coverage gaps, saturation (not_checked), 24-hour changes and provider incidents. include: ["entities"] adds a page of up to 50 entities as a table, about 30 tokens an entity. include: ["findings"] is not_checked.
infra_entity_get 500 tokens (2,000 with blocks) One entity of any kind with include blocks: metrics, saturation, changes, issues, coverage, config.

Every result carries basis, freshness, what was scanned, a cursor, why it is empty when it is, and the untrusted label.

Walking the fleet. The first call carries the summary and 40 entities (it must fit its 2,000-token ceiling); a call with a cursor returns the entities alone, 50 at a time, at the same filters. Two hundred entities cost under 8,000 tokens in all. A page the token budget cut resumes after its last row, so none is repeated or skipped. The walk is ordered by when each entity was FIRST seen, newest first, because that never changes: an entity that reports between two pages keeps its place instead of jumping past the cursor. When a fleet's names or change summaries are long enough to outgrow the price, the summary's text (or, for infra_entity_get, the entity's own names) is clipped and textClippedTo says to how many characters; counts, ids and times are never cut. The cursor is signed and bound to the project and the filters: another project, another filter set or an edited cursor is refused.

Reading 1,000 entities is recorded. The page whose running total reaches 1,000 rows writes one infra.entities.export audit row (the filter and the count, never a row) before the page is returned; a read that cannot be recorded is refused. It is a tripwire on one walk, not a quota.

Who owns it, how much it matters, and how many series it may spend

An entity can carry declared facts a person or an approved agent states: an owner, a team, tags, a tier (best_effort, standard, critical) and a protected flag. They are stored on the entity with the basis declared, and a collector's observations never overwrite them. Two governed writes change them, and a third kind of act is only ever a person's.

infra_entity_update (MCP) and PATCH .../infra/entities/:entityId (REST). The owner, team, tags, raising the tier, and setting protected. It is a governed write: the plan is digested, a human decides, and one apply lands against the entity's revision (a hash of the declared fields, so an edit through any other door between the yes and the retry closes the request unspent). The approval card names what the change touches: the approval-policy rows, alert rules and saved views whose stored conditions mention a changed value or the entity (a text match over what is stored, bounded, and labelled so). It is refused before anyone is asked when the change would move the entity under a looser approval-policy row (an agent may not make that move; a person with configure_infra may), and when it changes nothing. Clearing protected or lowering the tier is human-only (org:admin): the governed path refuses it, and a person makes it on the same REST route, where it is audited as infra_entity_protection.disable.

The series budget. A collector can send more series than a plan can afford, so each entity has a budget of live metric series: 230 on Free, 2,300 on Pro, 11,500 on Team, 46,000 on Enterprise at 60-second grain, and the whole project's collector has the same figure (raised by exactly what a person widened individual entities by). A series past a budget is folded into the metric's one overflow series instead of being dropped: its points are stored, only the per-series detail is gone, and the usage receipt says so under the reason infra_series_budget, apart from the older per-metric cap (metric_series_overflow). A series with no entity is not budgeted. If the budget cannot be read, series are admitted: the monitor is never the outage.

infra_series_budget_update (MCP) and PUT .../infra/series-budget (REST) lower the budget of one entity, or of one metric of one entity, as a governed write whose card carries the numbers the change is made on (the live series now above the proposed figure, which is exactly what would fold). POST .../infra/series-budget/preview returns the same numbers and writes nothing. A raise is a person's own act (billing:write, human-only): the MCP tool refuses it with that remedy, and the REST route performs it only for a person acting for themselves, audited as series_budget.widen. A protected entity bars every lever, so a narrowing on one is refused until a person clears it.

Asking for a change: restarts, scaling, rollbacks and collector rollouts

The two reads above show the fleet. A third family of tools lets an agent ask for a change on your platform. Every one of them only opens a request; a person decides, and what each is allowed to do is fixed by the act's class, not by the tool.

Tool What it asks for Platforms Who decides
infra_restart_propose A rolling restart of one workload Fly, Render, Railway, Heroku, DigitalOcean Two people
infra_scale_propose A new instance count for one workload, inside a band same Two people
release_rollback_propose Roll an environment back to an earlier release Vercel, Cloudflare Workers, Render An independent person (two when the organization says so)
collector_rollout_propose Roll a collector profile revision or a package upgrade out in waves your collectors A person approves the canary wave; each later wave is a person's act in the dashboard
provider_incidents_list Nothing: a read of whether a provider's own status feed reports an incident that overlaps your issues n/a n/a

Restart, scale and rollback are critical and denied by default. Their acts (workload.restart, mitigation.workload_scale, mitigation.release_rollback) ship as CRITICAL rows whose decision is DENY: until an organization deliberately relaxes the row to ASK, a call is refused with the engine's reason and nothing is stored. They are never ALLOW under any policy row, review mode or autonomy rung. The tools hold infra:act, which buys opening a request and nothing more; a proposer can neither approve nor apply what it opened. In Actions, the rollback act is live; the restart and scale acts are listed as planned.

  • Restart has no inverse (it is self-healing): no time limit and no revert, with a 30-minute verification on endpoint_error_rate instead. An agent may open at most two restarts of one workload in a rolling hour. A restart that would leave fewer healthy instances than the floor through the roll is refused before anyone is asked, as is a datastore, a protected entity, a workload with a change in flight and a platform with no lever provider.
  • Scale works only inside a band a person set (GET and PUT /orgs/:org/projects/:project/infra/lever-bands, minReplicas and maxReplicas per workload and lever). Setting a band is human-only, org admin, and has no tool: an agent could not be allowed to widen the band it then proposes inside. A scale outside the band, with no band, to zero, to the count already running, under platform autoscaling, or on a datastore is refused. The approver sees the count before and after, the band and the cost delta, and the previous count comes back by itself at the time limit (one hour by default, at most 24).
  • Rollback targets a deployment your resource catalog already holds, older than the current one and finished building. The approver sees the measured blast radius, or not_measured.
  • Collector rollout pushes nothing to your collectors: a released wave is the bundle Bucker renders and a draft pull request, and a person applies and merges them.
  • provider_incidents_list answers "is it us or them": per provider, incident_reported, none_reported or unknown. A stale, failing or missing feed reads unknown, never an all-clear, and a link between an incident and an issue is a correlation with a stated strength, not a cause.

The restart, scale, rollback and provider-incident tools sit in the infra toolset. The holds on the wider MCP surface were lifted by owner decision on 2026-11-16 without a signed-off security review of the OAuth server; see MCP setup. Approvals are described in Approvals and the agent rules in Agent governance.

REST

Route Purpose
PUT /orgs/:o/projects/:p/infra/series-budget Lower an entity's (or one metric's) series budget; a raise is the person's own act. A first call answers 202 with the request to decide; the retry names it in approvalRequestId.
POST /orgs/:o/projects/:p/infra/series-budget/preview What a proposed budget would fold. Writes nothing.
PATCH /orgs/:o/projects/:p/infra/entities/:entityId Declared owner, team, tags, tier and protected; same ask-then-retry shape. Needs configure_infra.
GET /orgs/:o/projects/:p/infra/digest The summary; include=entities adds a page; limit (at most 50), cursor, kind, provider, environment, service, signal with state.
GET /orgs/:o/projects/:p/infra/entities/:id/detail One entity; include=metrics,saturation,changes,issues,coverage,config.

The two reads need infra:read on the project and write nothing but the query log. The three writes need configure_infra (collection:write) on it. An entity of another project or organization is a 404 on every door, the same answer as an id that does not exist.