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, both held until the SG-059 security review: they need the infra:read scope (relation read_infra), which the telemetry:read tier does not grant and the live MCP scope ceiling does not hold, 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.

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.