Telemetry glossary
Defined terms used across the telemetry reference. Alphabetical.
Action key (Phase 2) — A symbolic name for a manifest mutation that an agent policy MAY authorize: disable_flag, set_rollout_percentage_to_zero, etc. See agent-policies § Actions.
Agent policy (Phase 2) — A version-controlled TOML file in agent-policies/<name>.toml that bounds the manifest writes an agent token may perform. See agent-policies.
Capabilities manifest — The structured, machine-readable description of what the running exd telemetry install can do, returned by exd telemetry capabilities --format json. See capabilities.
Citation chain (Phase 2 for the agent enforcement; the human-citation form ships in Phase 1) — The provenance-bearing trailer block on an agent-produced commit that traces the action back to the data and query that authorized it. See provenance § Citation format and agent-policies § Cited-finding requirement.
Dead flag — A flag whose every evaluation in a window returned the per-environment default value, suggesting it is no longer in use. Detected by T003.
Diagnostic — A structured observation produced by an analysis query, identified by a stable T-code with severity info, warning, or error. See diagnostics.
Evaluation reason — The cause of a flag's evaluation outcome: matched_rule, fallthrough, off, prerequisite_failed, error, or sdk_default. See evaluation-record § Evaluation reasons.
Evaluation record — The single, normative artifact produced for every flag evaluation. The only contract between SDKs and any downstream consumer. See evaluation-record.
Finding — The output of a exd telemetry invocation: the JSON envelope plus the diagnostic set it produced. Findings are cited by agents in commit trailers. See provenance.
Group (ExdClientGroup) — A multi-namespace SDK client backed by a single SSE connection that fans out version events to per-namespace inner clients. Records produced by any member flag namespace flow through one group-level sink (or per-member sinks if configured). See sinks § Multi-namespace clients.
Manifest version — The monotonically increasing integer assigned to each successful manifest upload. Carried in every EvaluationRecord so any evaluation can be pinned to the exact rule set that produced it. See evaluation-record.
Named query — A parameterized analysis runnable via exd telemetry run <name>. In Phase 1 the catalog consists exclusively of the built-in telemetry.* queries shipped with exd-client. The user-defined form declared in queries/<name>.toml is deferred indefinitely. See query-catalog.
Provenance block — The mandatory JSON object attached to every exd telemetry JSON output, carrying source URIs, time range, manifest versions observed, query version, engine, and timing. See provenance.
Q-code (deferred indefinitely) — A diagnostic in the lint vocabulary applied to telemetry-related TOML files (queries/*.toml, queries/thresholds.toml). Sits in the same lint pipeline as the manifest's E0xx / W0xx codes. The Q001–Q099 range is reserved against future use; no Q-code is implemented in Phase 1 because the files they would validate are not landed in the manifest tree. See query-catalog § Query lint diagnostics and thresholds § Lint rules.
Query catalog — In Phase 1, the built-in telemetry.* set shipped with exd-client. User-defined queries in a manifest repo's queries/ directory are deferred indefinitely. See query-catalog.
Reference sink — A sink implementation shipped with exd-client and gated on a Cargo feature: StdoutSink, FileSink, OtlpSink, ObjectStoreSink. See sinks § Reference sinks.
Remote-eval client — A client shape that performs no local evaluation and instead calls POST /api/v1/tenants/{tenant}/namespaces/{ns}/evaluate{,/all} on exd-server. The TypeScript @exd/client/remote module is the reference implementation. Records for remote-eval requests are produced server-side with sdk_name = "exd-server". See sinks § Remote-eval clients.
Rung — A discrete level of telemetry sophistication, from Rung 0 ("no telemetry") through Rung 5 ("streaming fan-out with auto-rollback"). The adoption ladder is summarized in the README § Adoption ladder.
Sample-ratio mismatch (SRM) — A statistically significant deviation between the observed and expected variant distribution. Detected by T001.
Schema version (telemetry) — The integer version of the EvaluationRecord schema, currently 1. Independent of the manifest schema version. See evaluation-record § Stability and evolution.
Secondary exposure — An evaluation by a flag's predicate that pulls in another flag, segment, or rule whose membership matters for analysis (holdouts, layered experiments). Encoded in secondary_unit_ids and matched_rule_id chains. See evaluation-record.
Sink — A pure-transport consumer of evaluation records. See sinks.
T-code — A stable diagnostic code emitted by analysis queries, e.g. T001. Numbered densely from T001; reserved range starts at T100. See diagnostics.
Threshold — A configurable numerical parameter governing when a T-code fires. In Phase 1, thresholds are sourced from CLI --thresholds <path> or built-in defaults; storing them at queries/thresholds.toml in the manifest tree is deferred indefinitely. See thresholds.
Trigger (Phase 2) — A clause in an agent policy that names a T-code whose detection authorizes a class of agent actions. See agent-policies.
Unit ID — The identifier used for variation bucketing. Hashed with SHA-256 and emitted as unit_id_hash in evaluation records, unless the flag namespace opts into raw IDs via raw_entity_ids = true. See evaluation-record § Privacy filtering.
Variant value (typed) — The discriminated-union encoding {type, value} carrying a flag's typed result in EvaluationRecord.variant_value. See evaluation-record § Variant value encoding.