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 theapm_red_rollupspillar off the score answersnot_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, sosdk_currentis judged once per project and shown on each service asscope: project.
The rules
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.
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.
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.
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.
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.
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.
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.
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.