Telecraft

Glossary

This glossary defines the words Telecraft uses. The documentation, the console, and the CLI all use each term exactly as it is defined here, so when a word is capitalised in a page it means what this page says. The terminology guide is the visual companion: it shows where Telecraft's words meet OpenTelemetry's, and where the two collide.

Topology

Term Meaning
Tier A position in your collection topology, such as edge or gateway. A Tier is an object you author and own, and it carries the policy for every collector at that position. Each Tier declares one Environment and binds one Blueprint version, and Telecraft renders one configuration artefact per Tier. A Tier is never a measure of how much something matters: that is Service Class.
Hop The directed link between two Tiers, or from a Tier to a destination. A Hop is an object you author and own. Trust belongs to the Hop, not to the Tiers at either end.
Path One Service's route through the Tiers to its backend. A Service can have several Paths, and that is normal. Telecraft derives the delivery Expectation for a Service from its Paths.
Collector A running OpenTelemetry Collector process (otelcol). You never author or draw a Collector: Telecraft matches each one into a Tier by selector, and it inherits that Tier's policy and Owner. If one collector needs different policy, split the Tier.
Estate Every collector Telecraft knows about, across all of your infrastructure. Telecraft says Estate rather than "fleet" so that the word never collides with the ElasticFleet integration.
Fleet (capital F) The Elastic product: Fleet Server and its UI in Kibana. It is never the Estate. In Telecraft it appears only as the qualified implementation name ElasticFleet.

Governance

Term Meaning
Service The unit Telecraft governs, identified by its service.name. 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 write a Service Class as "Tier N": a Tier is a position in the topology.
Sensitivity What kind of data a Service's telemetry carries, such as personal data or financial data. Sensitivity decides routing and redaction. It is separate from Service Class, which decides how complete the telemetry must be.
Requirement A versioned rule a Service must meet, about its configuration or its telemetry. Every Requirement carries its own fix, so a finding always tells you what to do.
Component A configured, named, versioned instance of a Catalogue type (receiver, processor, exporter, connector, or extension), with an Owner. A shared Component is a standalone file with the id <team>/<name>, and Blueprints use it by reference, pinned to a version unless they opt into track: head. A local Component is declared inside one Blueprint and cannot be used outside it.
Blueprint A named, versioned composition of Components, written as one ordered lane per signal plus collector-wide extensions. A Tier binds exactly one Blueprint version. A Blueprint's satisfies list names the Requirements it intends to meet; Telecraft checks that claim rather than trusting it.
Owner The person or group accountable for an authored object. Every authored object has exactly one Owner, and every Owner belongs to exactly one Team.
Team A group of Owners and child Teams, arranged in a tree where each Team has one parent. Compliance rolls up the tree, so a parent Team sees the results of every Team beneath it, waivers included. You supply Teams from your own source, teams.yaml by default.
Catalogue The inventory of collector component types for one collector release, keyed by (class, type): what exists, its stability per signal, and its lifecycle. Telecraft generates it from upstream metadata.yaml, keeps one per release, and judges each collector against the Catalogue for the version it runs. Authoring is judged against the version you have activated. You can add entries of your own. The Catalogue says what exists; the Allow-list says what a Team may use.
Activation Designating which imported version of the Catalogue or the Schema Registry your estate is judged against. It is explicit and audited: you read an impact report first, an operator decides, and the decision is recorded in activations.yaml alongside the report it was taken on. An operator here is somebody in a Team at the top of your team tree, because activating changes judgement for the whole Estate and no Team below the top answers for all of it. Nothing activates on its own, and activating changes judgement only: it never touches a running collector.
Impact report What changes when you activate a version, computed from the version you run and the one on offer before anything changes. For the Catalogue it covers components in use that the new version removes or deprecates, by Blueprint and Team, and stability changes that cross a floor. For the Schema Registry it covers attributes added and removed, requirement levels tightened, groups and attributes deprecated, and which Services stop passing. Where a report could not read something, it says so instead of reading silence as a clean bill.
Allow-list The part of the Catalogue a Team may use, keyed by (class, type). A Team's effective Allow-list is its parent's list narrowed by its own, plus any Grants, so a child Team can narrow but never widen. With no Allow-list, the whole Catalogue is allowed. It is authored in git, and it is the only rule that blocks a render.
Grant An exception, authored and owned by an ancestor Team, that adds named Catalogue entries to a descendant Team's effective Allow-list. It applies to that Team's whole subtree, and Teams below can still narrow it. Everything a Team may use traces back to the root Allow-list or to a Grant.
Endorsement A designation that the organisation stands behind a Blueprint at a named version, across the whole Estate. It is authored in endorsements.yaml by a Team at the top of the team tree, because endorsing speaks for every Team, and moving it to a newer version is a fresh pull request. An Endorsement that sits behind the Blueprint's current version stays visible and says so: it is a prompt to review the newer version, never a blessing of it.
Stability floor The minimum upstream stability a Service's Components must have, set per Service Class and Environment. Telecraft checks it per Component and per signal the Component handles. Falling below the floor raises a finding; it never blocks a render.
Palette What the composer offers you: the Catalogue entries your Team's Allow-list permits, judged live. Allowed entries show as normal, entries below the Stability floor are greyed with the reason, and entries outside the Allow-list are hidden. The Palette is presentation only; the render enforces the rules.
Environment The test, staging, or production dimension of a Service's deployment, matching deployment.environment.name. You define the values, and production is the one policy defaults attach to. Each Tier declares one Environment, so a Service in several Environments has sibling Tiers, one per Environment. An Environment is never called a "path": a Path is a route through the topology.
Satellite repo An optional repository that holds one Team subtree's authored content and rendered artefacts outside the main estate repository. Governance stays in the main repository: the Team is still listed in its teams.yaml, the mapping is declared centrally, and a satellite can reference the main repository but not the other way round. Verdicts are visible across the Estate even when the content is private to the subtree.
Schema Registry The versioned Weaver registry you maintain to say what your telemetry should look like: it imports the OpenTelemetry semantic conventions, tightens requirement levels, and adds your own namespaced attributes. You import and activate it like the Catalogue, and schema_conformance Requirements reference it. Always write the full name: "registry" on its own is ambiguous.
Placement Where a schema_conformance Requirement is checked. landed, the default, checks telemetry that has landed in a backend. live checks the findings the Live-check tap emitted at collection time.
Live-check tap The collection-time source of schema conformance findings that placement: live names: a weaver registry live-check service you deploy, fed by a sampled pipeline the renderer adds beside the lanes of a Tier that opts in with a live_check block. Its findings come home as ordinary log records, and a placement: live Requirement is judged against them.
Exemption A waiver for one Requirement, scoped to one object or one Team subtree, with a named Owner and an expiry date. It lives in git and needs review from the waived Requirement's Owner, so nobody can exempt themselves. An Exemption waives the count, never the diagnosis: the finding still shows, it stops counting against you. Renewal is a fresh pull request, and an expired Exemption that is still present is itself a finding.
Grace Period An onboarding window, set per Service Class, during which a new Service's findings are waived. The higher the class, the shorter the window.

Readings and verdicts

Term Meaning
Intended The configuration in git, pinned to a commit SHA. It includes configurations people commit by hand. This is what GitOps calls "declared"; Telecraft says Intended.
Effective The configuration the collector reports it is running, taken from OpAMP's EffectiveConfig exactly as the collector sends it. Telecraft never substitutes what an applier holds or what it believes it sent.
Observed The telemetry that arrived in a backend over a time window.
Known A flag on every reading that separates "Telecraft cannot see this" from "this is absent". Not knowing is a normal state, never a failure.
Outcome The verdict for one Requirement on one Service, from crossing Effective with Observed. One of compliant, not_configured, broken_pipeline, not_delivered, ungoverned, misconfigured, or unknown, plus library_drift, which never comes from the cross.
library_drift A finding that says the subject passes the version it claims or pins but fails the current one. The rule moved and the subject has not caught up. It has three facets: the Requirement version a configuration claims, the Component version a Blueprint pins, and the Schema Registry version a Requirement pins while the estate has activated a newer one. For the first two the fix is to review the version diff and open a change proposal, not to instrument again; for the third it is to close the instrumentation gap the active version names, then move the pin.
Delivery status Whether the collector applied the configuration Telecraft sent it, in OpAMP's own words: UNSET, APPLYING, APPLIED, or FAILED. It compares Intended with Effective, per collector, and sits beside the conformance verdict.
Mutation profile The list of changes a delivery path may make to a configuration on its way to the collector: exact, supervisor, or elastic-fleet. Telecraft applies it before it compares digests, so digests from different profiles are never compared with each other. Entries are patterns, never literal values.
Expectation What the Intended configuration implies should be observable: which signals should arrive for each Service and Environment, which attributes they should carry, and which self-telemetry each Tier's Components should emit. Telecraft derives it from the configuration at a commit SHA; you never author one. A failed Expectation means "the configuration did not work", which is different from "the telemetry is wrong" (conformance) and "the configuration never applied" (delivery). When a reading is unavailable the Expectation is unknown, never failed.

Serving

Term Meaning
Instance One running Telecraft: one Instance server over one estate, with its own users, its own activated versions, and its own verdicts. Everything Telecraft judges belongs to exactly one Instance, so keeping two groups' estates apart from each other means one Instance each. An Instance is never a collector process: one start of a collector is an Incarnation.
Instance server The long-running Telecraft process. It serves the console you sign in to, the API behind it, and the configuration Served collectors fetch, all from one estate. It holds nothing that outlives it: restarting it signs everybody out and loses no record.
Organisation The unit Telecraft keeps apart from every other: one Organisation has its own estate, its own people, its own findings, and its own Instance. Everything Telecraft judges belongs to exactly one Organisation, and nothing an Organisation authors can name anything in another. A deployment serving several Organisations runs one Instance for each.
Provisioner The component that runs a deployment of many Organisations. It reads the register of Organisations and creates, addresses, and retires one Instance for each. It never reads what is inside one: it holds names, addresses, and lifecycle state, and no configuration, findings, or verdicts.
Supervisor The upstream OpAMP Supervisor (opampsupervisor). Every Served collector runs one beside it.
Served A collector that receives its configuration from Telecraft's OpAMP server.
Foreign A collector whose configuration arrives by any other route: GitOps, configuration management, or a person. Foreign collectors are governed exactly like Served ones.
Delivery path How a collector gets its configuration: Served, or delivered through git. Telecraft shows it for every collector.
Forge adapter The interface between Telecraft and your git host's API, used for change proposals, review routing, and attribution. Each implementation is named after the product, starting with the GitHub App. Beneath it, plain git transport over a deploy key or token always works, and governance never depends on a forge feature.
Secret name The name an estate file uses to point at secret material without carrying it, such as the client secret of an identity provider. It is lower-case letters, digits, and hyphens, and it never describes a path. Telecraft resolves it to a file of that name in the Secret directory. The estate names secret material; it never holds any.
Secret directory The directory Telecraft reads secret material from, and the only place it looks. One file per Secret name, the file's contents the value. How the directory is filled is your deployment's business: files on a host, a compose secret, a Kubernetes Secret mounted read-only, or anything else that writes a file. Telecraft never fetches secret material over the network.
Hosted repository The estate repository Telecraft keeps for your Organisation when you have no git host of your own to point it at. It is an ordinary git remote: you clone it, push to it, and run your own checks against it. Authoring opens pull requests, so opening them needs a repository on a git host you have connected, and you can move a Hosted repository to one at any time by pushing it there. Every clone you take is a complete copy, history included.
Connected repository The estate repository Telecraft uses when your Organisation points at a repository on a git host of your own. You install Telecraft on that host and choose which repositories it may reach, and it opens its pull requests there, so review routing and merge rights stay yours. It reaches only the repositories you selected, and uninstalling it withdraws every bit of its access at once. Reading, judging, and delivery carry on from the copy it last fetched, and it tells you how old that copy is.
Account administrator The person who holds an Organisation's account with the hosted service. They see the subscription, supply the values of secrets the estate names, connect a git host, add another administrator, and ask for the Organisation to be closed. It is a separate authority from ownership: being an Account administrator gives you nothing inside the estate, and owning something in the estate gives you nothing on the account.
Account store Where the hosted service keeps the people who hold accounts with it: the address and name they gave, the provider they sign in with, and which Organisations they administer. It exists only in a deployment that sells accounts, so a self-managed Telecraft has none and needs none: its people are authored in its estate. It holds nothing about what anybody may read or own inside an estate, which only an Instance knows. Asking to be removed deletes what it holds about you.
Register of Organisations The authored list of which Organisations a deployment runs, one record each: the name, the address its Instance answers on, where its estate comes from, who holds the account, and whether it is running or retired. It holds nothing that is inside an Organisation. A retired record keeps its name for ever and the name is never issued again, because an address that once belonged to somebody is still in bookmarks.

Delivery & rollout

Term Meaning
Rollout An optional authored object, owned by the Tier's Owner, that moves one Tier from one Blueprint version to another in stages. While a Rollout is active the Tier is bound to both versions and rendered/ holds both artefacts. Telecraft proposes each stage as a pull request and you merge it; withholding the merge halts the Rollout, and aborting is another proposed pull request. A Tier has at most one active Rollout, and a plain rebind is always available instead.
Cohort The part of a Tier's collectors that a Rollout stage applies to. You specify it as named hosts, an attribute selector, a fraction, or a combination; Telecraft computes membership when it serves, and stores nothing. On the Foreign path a Cohort is advisory: a collector outside it lags, it does not fail.
Unmatched artefact The rendered configuration Telecraft serves to a collector that matches no Tier selector. It is owned by the root Team, stamped with the commit, and has self-telemetry on and no data pipelines, so an ungoverned collector is visible rather than silent. It is not the Quarantine destination, which handles data rather than collectors.
never_seen A finding on a Tier whose selector has never matched a collector. Without a Population floor it is neutral: no compliance ratio counts it, Telecraft never shows it red, and its age tells you how stale the Tier is. Once the Tier has a Population floor above zero and the zero persists past the grace window, it becomes a violation.
under_populated A finding on a Tier whose selector matches collectors, but fewer than its Population floor, for longer than the grace window (for example, "expected 40, seen 12"). It is not a milder never_seen: the Tier has readings. It routes to the Tier's Owner.
Population floor The minimum number of collectors a Tier's selector should match. Telecraft derives it from your infrastructure through the inventory provider, or you declare it as min_expected in the Tier file. No floor means no finding. It is a floor, not an exact count: more collectors than expected is never a finding.
Quarantine destination A short-retention destination that a gateway routing rule you author sends telemetry with an unrecognised service.name to. Telecraft watches it and flags what arrives, so you can onboard the sources. It is a rendered pattern in your configuration, not something Telecraft runs, and it empties through onboarding, not through retention.

Pipeline observability

Term Meaning
Claim One checkable assertion inside an Expectation, derived from a rendered artefact at a commit SHA. An arrival Claim says a signal should land for a Service in an Environment; an enrichment Claim says attributes the configuration inserts should be present on landed telemetry; a self-telemetry Claim says each Component in a Tier should emit its own telemetry. Telecraft claims only what it reads from the artefact, so where the configuration says nothing the result is unknown, never red.
expectation (finding kind) The finding kind a failed Claim raises, with its own column in the Team roll-up. A data Claim with no Requirement behind it raises an advisory finding on the Service, which also catches dead configuration. A pipeline Claim raises a finding on the Tier, routed to its Owner, and can become a violation once the Settle window has passed. A data Claim backed by a Requirement raises no finding of this kind: it feeds the Observed side of that Requirement's Outcome instead.
Settle window The period after a configuration reaches APPLIED at a new commit during which its Claims read as pending, neither red nor green. Self-telemetry Claims settle in seconds; arrival and enrichment Claims take longer. It is separate from the observation window a Claim looks back over.
Reduction How much less data leaves a Tier than enters it, per signal. Telecraft shows the figure and never judges it: a filter that drops 90% of its input is doing its job. The meter's only red readings are error rates (refused, send_failed, enqueue_failed).
Metering The flow readings Telecraft computes on read through the telemetry provider and stores nowhere: throughput, volume, and freshness. Pipeline-grain readings come from self-telemetry, per Tier and signal; service-grain readings come from Observed data, per service.name. The two are never mixed.
Self-telemetry destination The endpoint you declare for the Estate where every rendered configuration sends the collector's own metrics and logs. Telecraft resolves it per Tier at render time. A Tier's self-telemetry never depends on that Tier's own data pipelines; if it passes through another Tier and that Tier fails, the reading becomes Known: false, never red.
Incarnation One start of a collector process, identified by its service.instance.id, which changes on every restart. Incarnation churn per Tier is the restart-rate reading. To follow one collector across restarts, Telecraft uses the infrastructure's own identity where it offers one.

Console

Term Meaning
Workspace One of the console's five areas: Home, Estate, Topology, Compose, and Catalogue & Governance. Each Workspace offers several views over the same model, and your selection, filters, and Environment lens survive switching between them. You reach an object through global search, not by browsing to it.
Home The console's landing, and the only Workspace named for a place rather than an activity: it answers "where do I look first?". It judges nothing of its own, showing the estate's standing and its worst Tiers, Teams, ungoverned collectors and Rollouts as the surfaces that own them show them. Every element on it is a door into the Workspace that can act, and every list says what it left out.
Shelf The landing surface of the Estate Workspace: a grid of cards, one per Tier, grouped by Team subtree and lined up by Environment with production first, with the worst problems first. It starts on your own Team's subtree. Healthy cards sink to the end but never disappear; an all-healthy section collapses to one summary line.
Environment lens The control in the strip above every console Workspace that picks which Environment leads, production by default. It sets emphasis and evaluation context, not a filter: the chosen Environment draws first and in full, and the others stay on the page as summary lines carrying their counts. Your choice is remembered, and a lens in a URL overrides it.
Claim flow The console flow that takes one or more ungoverned collectors into governance. You start from a group of collectors, the console suggests a selector built from the identity attributes they share (never a list of instance ids), and you attach them to an existing Tier or draft a new one. It always ends as a pull request in your name, with a preview of the rendered impact. It is not quarantine routing, which belongs to Compose.
Canvas engine The shared library that lays out both the composer canvas and the topology canvas: the model goes in and the geometry comes out. Layout is deterministic and row-constrained, with orthogonal routing and per-signal bend offsets, and its layout rules hold no matter how you interact with the canvas.
Presentation store The only state the console keeps outside git: your presentation preferences, such as the Environment lens, collapsed sections, canvas arrangement within a row, and which Tours you have seen. It is never model truth. Losing it changes what the console shows first, never what it asserts.
Tour An ordered sequence of Steps that teaches the console using your own Estate. A Tour navigates and points; it never clicks, authors, or invents. Its position lives in the URL like every other console state, so you can link to a Step. Tours teach the console; the documentation teaches the product. A Tour is not onboarding: onboarding is a collector joining governance.
Step One stop in a Tour: prose, an optional anchor naming an element by data-tour, and an optional destination route. An anchored Step points at its element without blocking it; an unanchored Step, such as the welcome, renders centred. If an anchor cannot be found the Step renders centred rather than failing. A Step is not a Rollout stage.

Editions and licensing

Term Meaning
Edition Which set of capabilities an Instance may use. Standard Edition needs no licence, costs nothing, and is unrestricted in production and commercially; it is what the documentation describes and what the public demo runs. Enterprise Edition is Standard Edition plus the Entitlements a valid licence file names. A capability that Standard Edition offers today stays in Standard Edition: the paid Edition only ever covers capabilities added after it existed.
Entitlement One named capability that an Enterprise Edition licence grants, such as running many isolated domains from one deployment. An Instance has an Entitlement or it does not; there is no partial grant and no quantity.
Licence file The file that puts an Instance in Enterprise Edition: a signed document naming the licensee, the dates it is valid between, and the Entitlements it grants. Telecraft verifies it against keys inside its own binary, so verification works with no network at all and nothing about your Instance is sent anywhere. It names you, not a machine, and Telecraft counts nothing against it. Losing the file, or letting it run past its expiry date, never stops a collector being served.