Telecraft documentation · companion to the glossary
Two vocabularies, one product
Every word Telecraft uses comes from one of two dictionaries: OTel's words, the upstream OpenTelemetry terms used exactly as OpenTelemetry defines them, and Telecraft's words, the product's own model layered on top. The traps are where the two collide.
1 · OTel's words: inside one collector
OpenTelemetry defines three signals: traces (what happened to one request, as a tree of spans), metrics (numbers aggregated over time), and logs (timestamped records). See the signals documentation. Applications emit them through SDKs, and a Collector is the standalone process that receives, transforms, and forwards them.
| Word | Meaning |
|---|---|
| receiver | Gets data in, either by listening (for example otlp) or by scraping and collecting (for example filelog, hostmetrics, prometheus). |
| processor | Transforms data in flight: batches, limits memory, adds or strips attributes, redacts, samples. Processors run in the order you declare them. |
| exporter | Sends data on, to a backend or to another collector. |
| connector | Both an exporter and a receiver: joins the end of one pipeline to the start of another (for example, to derive metrics from spans). |
| extension | A capability outside the data path: health endpoints, authentication, the opamp reporting extension. |
| OTLP | The OpenTelemetry protocol: the wire format all three signals share. |
| resource | Attributes that describe the thing emitting the telemetry (service.name, k8s.pod.name). They are attached to everything the process emits. |
| semantic conventions | The standard names for attributes and metrics, each with a requirement level (required, recommended, or opt-in). They define what well-formed telemetry looks like. Semantic conventions. |
| OpAMP | The control protocol (in beta): a collector, or its Supervisor, connects to a server, reports its status and effective config, and can receive config. It is transport, not policy. OpAMP specification. |
| Supervisor | A separate process beside a collector that applies remote config and manages the collector's lifecycle. The in-process opamp extension only reports. |
2 · Telecraft's words: outside, across the Estate
OTel's vocabulary stops at the edge of one process. Telecraft governs the whole population of collectors, so it adds a second layer of words, and it never reuses an OTel word to mean something different.
| Word | Meaning | Watch out |
|---|---|---|
| Tier | A position in the topology (edge, gateway). You author it, it has an Owner, and it carries the policy for everything at that position. | Only ever a position. How much a Service matters is its Service Class, never "Tier 1". |
| Hop | The directed link between two Tiers. It is an object with its own Owner: trust belongs to it, and the delivery Expectation crosses it. | In most tools this is only a string: an endpoint typed into an exporter. In Telecraft it is an object you can own and reason about. |
| Path | One Service's route through the Tier graph. Several Paths per Service is normal. | Not "pipeline": that word belongs to OTel and means the wiring inside one collector. |
| Estate | The whole population of collectors, across every kind of infrastructure (Kubernetes, VMs, bare metal). | Not "fleet": capital-F Fleet is Elastic's product (ElasticFleet), so Telecraft avoids the word. |
| Service | The unit Telecraft governs, identified by service.name, OTel's own identity attribute. | Every Service has a Service Class and is judged against its Requirements. |
| Service Class | How much a Service matters: C1 matters most, then C2, then C3. You can rename the values. A higher class must meet everything a lower class must, plus more. | Never written "Tier N": a Tier is a position in the topology. |
| Sensitivity | What the data is (personal data, financial data, and so on). Sensitivity drives routing and redaction, never completeness. | Keep it separate from Service Class: "how much telemetry" and "who may see it" are different questions. |
| Component | A configured instance of a Catalogue type (receiver, processor, exporter, connector, extension): named, versioned, and owned. The gateway team owns the gateway exporter; the security team owns the PII redactor. | Blueprints use a Component by reference, never by copy, so when the owning team changes it every consumer re-renders. |
| Blueprint | A named, versioned composition of Components, often from several teams, written as one ordered lane per signal, plus a satisfies list of Requirement ids: a claim of intent, never of fact. | A lane is ordered, not a set. Merging Components as a set produces valid-looking configs with memory_limiter in the wrong place. |
| Owner / Team | Every authored object has an Owner, in the style of CODEOWNERS. Owners belong to Teams, Teams nest, and compliance rolls up the tree. | Findings go to the Owner of the object, not to whoever owns the file it renders into. |
3 · The three readings, and why green means "it worked"
| Reading | Question | Source |
|---|---|---|
| Intended | What should this collector run? | Git, pinned to a commit SHA. GitOps calls this "declared"; Telecraft says Intended |
| Effective | What does it say it is running? | The config the collector reports it is running: OpAMP's EffectiveConfig, exactly as the collector sends it |
| Observed | What telemetry actually arrived? | The backend, over a window |
unknown or
not_delivered, never a silent pass or fail. Delivery status (Intended × Effective,
per collector) sits beside this, in OpAMP's own words: APPLYING · APPLIED · FAILED.4 · The traps: where the two dictionaries collide
EffectiveConfig, exactly as the collector sends it.ElasticFleet. The population of collectors is the
Estate. Telecraft also avoids calling collectors "agents", because
Elastic Agent is a different product; the only "agent" is in OpAMP's own protocol messages.5 · Check yourself
From memory, without notes
A Tier is a position. Service Class is how much a Service matters; a Hop is the link between two Tiers; a Path is a Service's whole route.
That's the otelcol pipeline: always in-process, per signal. A connector joins two pipelines; extensions sit outside the data path; a Blueprint is Telecraft's composition of Components.
Effective, OpAMP's own word. "Declared" is GitOps vocabulary for the git side, which Telecraft calls Intended; Observed is what landed in the backend.
Effective yes × Observed no = broken_pipeline. not_delivered means Telecraft can't see the Effective side; ungoverned is the opposite cell (arriving, but nobody authored it).
Components, Blueprints, Tiers, Hops, Paths, and Services are authored and carry Owners. Collectors are derived by selector match; the Estate is the population; verdicts are computed.
A Component: a configured, versioned, owned instance of a Catalogue type, used by reference, so the gateway team's change re-renders every consumer. The Catalogue is the inventory of types; the Palette is what the console offers you.
Primary source
If you read one thing, read the official Collector configuration documentation: it takes 20 minutes, and every OTel word above appears in a real config. For Telecraft's layer, the reference is the glossary, which the code, the console, and the documentation all follow.