Key concepts

This page defines the terms used throughout Telflo and these docs.

Configuration

A configuration is a named project: one canvas, one generated YAML document, and its version history. It is the unit you create, name, and open in the editor. A configuration is also built for one collector distribution, chosen when you create it and locked for the life of the configuration.

Flow

A flow is a prebuilt collector configuration from Telflo's curated catalog, each solving one problem. Using a flow creates your own independent configuration from it, locked to the flow's collector distribution and pinned to the collector version the flow was validated against. If the flow's distribution is not available to your account, the copy is created on OpenTelemetry Collector Contrib at its default collector version instead. From the CLI, telflo flows pull writes a flow's YAML to standard output or a file, and telflo config create starts a configuration from it, always on OpenTelemetry Collector Contrib. See Flows.

Version

A version is a snapshot of a configuration's canvas and YAML at a point in time, with an optional name. Saving updates the current version in place; a new version is created when you save edits to a read-only version or copy a version. The CLI follows the same rule: telflo config push edits the latest draft in place, or appends a new version when the latest version is published.

• The current version is the one you are editing.
• A published version is read-only. You can still edit its canvas, and saving prompts you to record the changes as a new version.

See Versions & publishing.

Pipeline

A pipeline carries one signal type (traces, metrics, or logs) through a chain of receivers, processors, and exporters. A configuration can contain multiple pipelines, including custom-named pipelines such as traces/production. On the canvas, pipeline membership is defined by the edges you draw, and each pipeline is color-coded. The one exception is the routing connector: its target pipelines are declared in its configuration, and Telflo draws dashed, read-only edges to them. See Canvas & pipelines.

Collector distribution

A collector distribution is the build of the OpenTelemetry Collector that a configuration targets. Every configuration targets one distribution, chosen when the configuration is created and locked for the configuration's lifetime: OpenTelemetry Collector Contrib, the full upstream component catalog and the default, or ClickStack, ClickHouse's collector build with a smaller component set, available in private preview. The distribution decides which components the palette offers, which collector binary validates and tests the configuration, and which collector versions can be selected. The editor toolbar shows it next to Collector: with a lock icon, and the configurations list shows it as a tag and in the Distribution column. To target a different distribution, create a new configuration. Through the API and the CLI, only OpenTelemetry Collector Contrib can be named when a configuration is created, validated, or tested; a configuration already locked to ClickStack keeps its distribution and stays readable there. See Managing configurations.

Collector version

Each configuration targets a specific OpenTelemetry Collector version within its distribution, selected from the collector version dropdown beside Collector: in the toolbar. The collector version determines which components and fields are valid, and which collector binary runs during validation and tests. The version can differ between versions of a configuration; the distribution cannot.

Publishing

A saved version is private to the editor. Publishing marks a version as a release that can be deployed. Only published versions can be assigned to a fleet's deploy groups. See Versions & publishing.

Fleet

A fleet is a named group of collectors managed together. You create and manage fleets in the Fleet section. In a server fleet, Linux servers & VMs in the Create a new fleet dialog, each collector connects to Telflo and pulls the configuration assigned to its deploy group. In a Kubernetes bridge fleet, Kubernetes (Operator bridge), one bridge connects to Telflo and manages the cluster's collectors, each with its own assigned configuration. A Kubernetes supervisor fleet, Kubernetes (Helm), available in private preview, runs supervisor-managed collectors in a cluster without the Operator. A Kubernetes fleet type that is not yet enabled for your account shows a Private Preview badge in the dialog and cannot be selected. See Fleet management.

Deploy group

A deploy group is a named group of collectors in a server fleet or a Kubernetes supervisor fleet. Each group holds an assigned configuration version, an assigned variable group, and any volume mounts its collectors need when they run in a container, so different groups in one fleet can run different configurations. The API and the CLI call a deploy group a deployment. Every new server fleet starts with a group named Default; in a Kubernetes supervisor fleet, each group is a role: node, cluster, or a gateway pool. Groups are managed on the fleet's Deploy Groups tab. See Create a fleet.

Instance

An instance is a single collector that has enrolled in a fleet, listed on the fleet's Collectors tab with its status and the configuration version it runs. On a server fleet, the statuses are In sync, Pending pickup, Applying, Apply failed, and Stale. Kubernetes bridge fleets report through the bridge and use their own status set. See Kubernetes fleets.

Organization

Your work belongs to an organization. Members of an organization share its configurations and fleets. Each member has a role, Admin or Contributor, that controls what they can do. See Members & roles.

Vault

The vault stores reusable values. Organization variables are shared across the organization and referenced from a configuration as $orgvar:NAME tokens that Telflo resolves when each collector checks in. User variables are personal to your account; selecting one inserts its value into the field. See Vault.

Service account

A service account is a machine identity in an organization, created by an admin, that holds one or more API tokens: the bearer credentials for the Telflo API, the Telflo CLI, and the MCP server. Each token is read-only or read and write, and is shown once when it is created. The account is a member of the organization with the Contributor role, and work done with a token is attributed to it. See Service accounts.

CLI

The Telflo CLI, telflo, works with configurations, fleets, and flows from a terminal, a CI pipeline, or an AI coding agent, through the same Telflo API as any other API client, so its changes appear in the web app immediately. A person signs in through the browser with telflo login, and the CLI then acts as that person in the organization they chose; automation sets TELFLO_API_TOKEN to a service account's token and acts as the service account. See CLI.

MCP server

The Telflo MCP server, hosted at https://mcp.telflo.com/mcp, gives AI agents such as Claude Code, Cursor, and claude.ai the CLI's operations as tools: reading and pushing configurations, validating and testing them, and deploying them to fleets. It calls the same Telflo API with the same access as the CLI. You connect it in the agent's MCP settings and either sign in through the browser, so the agent acts as you, or give it a service account's token. See MCP server.