# The Instrumentation Score

"How good is our telemetry?" has a number: the **Instrumentation Score**, 0 to 100, per service and
environment. It is computed from data Bucker already holds at ingest, by rules published on this page,
and every rule that fails comes with the evidence behind it and one recipe that fixes it. No model
decides a score.

The rule set is `instrumentation_score_rules_v1`, pinned to the `instrumentation-score/spec` draft
(revision `draft-2026-10`). The spec is a draft; a change to the pinned revision is a new rules version,
never a silent change to the old one.

Read it with `instrumentation_health_get` and `include: [score]` (read, `project:read`), or from the SDK
health card. The score comes from the last 24 hours.

## How the score is computed

Each rule has an impact level and a weight: **critical 40, important 30, normal 20, low 10**. A rule
judges some number of items (requests, error spans, log records, producers) and finds some failing; its
*pass ratio* is `(judged - failing) / judged`. The score is

```
round( 100 * sum(weight * passRatio) / sum(weight) )
```

over the rules that could be judged. A rule the data cannot judge is `not_checked`, with a reason, and is
left out of both sums. It is never counted as a pass. Each service reports its `coverage` (rules judged
over rules defined), so a 100 over four rules reads differently from a 100 over eight. A service with
nothing judged has the score `null`.

A rule *fails* when its pass ratio is under its pass threshold (1 for most rules; 0.95 for
`resource_attributes`). A failing rule lists its counts, up to three sample handles (hydrating one needs
`event:read`; names in samples are written by the sending client and are shown as data), and its recipe.

The arithmetic is a pure function of the rule results, so the score can be recomputed by hand from the
evidence the response carries.

## Where the figures come from

* **APM rollups** (`service_red_hours`, counted at the span writer before any sampler): service names,
  versions, entry operations, overflow folds, stated head sampling. With the `apm_red_rollups` pillar off
  the score answers `not_available`, never a score computed from nothing.
* **The hourly SDK inventory** (`project_sdk_hours`): which SDKs sent. The inventory is keyed by project,
  not by service, so `sdk_current` is judged once per project and shown on each service as `scope: project`.

## The rules

<a id="rule-service_name_set"></a>
### service_name_set (critical)

Passes when no request is attributed to an empty service name or one beginning `unknown_service`.

**Recipe.** Set `service.name` in the SDK or exporter resource, or `OTEL_SERVICE_NAME`.

<a id="rule-resource_attributes"></a>
### resource_attributes (important)

Passes when at least 95 percent of requests carry `service.version`.
`deployment.environment.name` is read once a counter for it is kept.

**Recipe.** Set `service.version` and `deployment.environment.name` on the resource.

<a id="rule-span_status_on_errors"></a>
### span_status_on_errors (critical)

Passes when every error span (one with an exception event or an error attribute) states status `ERROR`.
`not_checked` / `counter_not_kept` today: ingest does not yet count error spans without a status.

**Recipe.** Record the exception with `recordException` and set the status to `ERROR` in the handler.

<a id="rule-http_route_templated"></a>
### http_route_templated (important)

Passes when no entry (server or consumer) operation name contains a raw identifier segment: a number of
four or more digits, a UUID or a hex string of 16 or more characters. The pass ratio is the share of
requests on templated names.

**Recipe.** Name server spans by the route template (`/orders/:id`), not the concrete path.

<a id="rule-span_name_cardinality"></a>
### span_name_cardinality (normal)

Passes when the service has at most 200 distinct entry operations and none of its requests were folded
into an overflow row by the writer's caps.

**Recipe.** Move variable parts (ids, query strings, user input) out of span names into attributes.

<a id="rule-logs_trace_context"></a>
### logs_trace_context (normal)

Passes when every log record of a service that also sends traces carries a trace id.
`not_checked` / `counter_not_kept` today.

**Recipe.** Enable the logging instrumentation that injects trace and span ids into log records.

<a id="rule-sdk_current"></a>
### sdk_current (low)

Passes when no producer that sent in the window is below its declared floor or two minors (or 120 days)
behind the newest version in `sdk-versions.json`. OpenTelemetry exporters are not judged.

**Recipe.** Upgrade the SDK to the newest published version.

<a id="rule-sampling_declared"></a>
### sampling_declared (low)

Passes when every rollup row with client-reported drops before export also states a head-sampling rate
below 1.

**Recipe.** Configure the SDK sampler through its sample-rate option so the rate is stated on every trace.

## Muting and findings

Muting a rule is the existing `instrumentation_check.mute` (SDK-01), through `instrumentation_checks_update`:
sensitive, asks, 30 days at most. The score reads the rule results as they are; a mute silences a finding,
not a score.
