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.