Quickstart
Build an OpenTelemetry Collector configuration and deploy it to a running collector in a fleet.
This quickstart takes you from an empty canvas to a configuration running on a collector. You build a pipeline, publish it as a release, create a fleet, assign the configuration to the fleet's deploy group, install one collector, and watch it pull the configuration and report In sync, without logging into the host. The core path takes about 15 minutes.
Before you begin
- A Telflo account. Sign in at telflo.com.
- A host where you can run a collector. Collectors run on Linux (arm64 or amd64/x86_64), in a container or directly on the host. A host with Docker is the quickest option. To manage collectors in a Kubernetes cluster instead, see Kubernetes fleets.
- Fleet management enabled for your account. The Fleet section in the navigation is usable when it is enabled.
- For the AI build path only: AI enabled in Settings > AI, and access granted to your account. See AI access.
You can explore the editor without an account in the public editor, but you must sign in to save, publish, and deploy. This quickstart deploys a configuration, so sign in first.
Create a configuration
A configuration is a named project: one canvas, one generated YAML document, and its version history.
- Sign in at telflo.com. The Configurations list opens.
- Select New Configuration, then select Blank configuration and enter a name and an optional description. The editor opens on an empty canvas, with the component palette on the left, the canvas in the center, and the toolbar along the top. To begin from a prebuilt configuration instead, select Start from a flow; this quickstart builds from scratch. See Flows.
- Leave the collector version in the toolbar at its default unless you target a specific version. To rename the configuration later, select its name in the toolbar.
Build a pipeline
Build a minimal but real pipeline: receive OTLP, batch it, and export it. Choose either path below. Both produce the same standard Collector YAML, and the rest of the quickstart is identical.
- From the palette, drag an OTLP receiver onto the canvas. The
otlpreceiver accepts telemetry from instrumented applications. - Drag a Batch processor onto the canvas.
batchgroups telemetry before export and is recommended on most pipelines. - Drag an OTLP exporter onto the canvas.
otlpforwards telemetry to a backend. To watch output while you learn, also add a Debug exporter, which prints telemetry to the collector console. - Connect the components. Drag from the receiver's output handle to the processor, then from the processor to each exporter. Telflo adds the connected components to a pipeline for the matching signal type.
- Select the OTLP exporter and set its endpoint in the configuration panel on the right, such as your backend's OTLP endpoint. To keep credentials out of the YAML, reference an environment variable with
${env:NAME}. To share a value such as an endpoint across configurations, reference an organization variable from the vault by typing@in the field.
The AI button appears in the toolbar when AI is enabled and access is granted for your account. See AI access.
- Select AI in the toolbar. The assistant opens as a docked panel, and the navigation menu and right panel collapse to make room.
- In Plan mode, describe the pipeline you want, such as "Receive OTLP, batch it, and export over OTLP to my backend." The assistant proposes a design and asks follow-up questions.
- Switch to Build mode to generate the configuration. The components appear on the canvas and in the YAML as if you placed them.
- Review the result on the canvas. Adjust any component, such as the exporter endpoint, in the configuration panel; expand the right panel from its rail if it is collapsed.
Select the YAML tab to see the generated configuration, including the service.pipelines block. Edits on the canvas and in the YAML stay in sync.
Validate the configuration
Telflo validates the configuration continuously as you build, so problems surface before you deploy. The editor shows a status row with the result: config valid with the collector version, or the number of errors.
Expand the status row to see each issue, with the affected component and a description. Resolve every error before you publish. See Validation.
Validation confirms that the configuration is well-formed. To confirm what it does to real telemetry, run sample data through it on the Testing tab. The Testing tab appears when testing is enabled for your account. See Testing.
Publish a version
Only published versions can be deployed to a fleet.
- Select Save in the toolbar. Telflo records a version of the current canvas and YAML.
- Select Publish in the toolbar. The Publish Configuration dialog opens; any pending changes are saved first, so the published version matches the canvas.
- Confirm in the dialog.
The version is now a release, available to assign to a fleet's deploy group. See Versions & publishing.
Create a fleet
A fleet is a named group of collectors managed together.
- Go to Fleet and select New Fleet, then select Linux servers & VMs. The New server fleet dialog opens.
- Enter a Name that is unique within your organization.
- Set the Token expiry: Never, 180 days, 1 year, or 2 years. Telflo recommends a bounded expiry for long-lived fleets, so an exposed token cannot be used indefinitely.
- Select Create fleet.
The new fleet opens on its detail page with a Set up this fleet checklist covering the next two steps: assign a configuration and install a collector. Creating the fleet issues an install token, the credential your collectors use to connect to Telflo and identify themselves as part of this fleet. The fleet starts with one deploy group, named Default, which holds the configuration its collectors run. See Create a fleet.
Assign the configuration
Assign the published version to the fleet's deploy group.
- Select Assign on the checklist's first step, or select Assign on the Default group of the Deploy Groups tab. The Assign a configuration to Default dialog opens.
- Choose the configuration you published and its version, then select Assign.
The group now serves that version to every collector deployed from it.
Install a collector
Install a collector from the deploy group's install dialog. Every install option is preconfigured with the fleet's connection endpoint, so the collector connects to the right fleet. Collectors run on Linux (arm64 or amd64/x86_64), in a container or directly on a host.
- Select Install on the checklist's second step, or select Install on the Default group of the Deploy Groups tab. The Install collectors dialog opens.
- Keep the default Container image (GHCR) platform. It runs Telflo's prebuilt collector image with no build step, which is the quickest way to bring up your first collector. Select Reveal & copy command and run the copied command on a host with Docker.
- To install without the prebuilt image instead, select a server platform matching your host's architecture, then install with one of the two options:
- Quick Deploy. Copy the generated command and run it on the host. It downloads the bundle, sets the fleet's token, and starts the collector in one step. By default it registers the collector as a systemd service that starts on boot. Generate a fresh command for each host, because the Quick Deploy URL expires.
- Download. Clear the systemd service option, download the zip, and follow its README. After the download, the dialog shows the
OPAMP_TOKENenvironment variable to set on the host before running the bundle's start script.
The run command, the Quick Deploy command, and the OPAMP_TOKEN value all carry the fleet's install token, which is a credential. Share them over a secure channel and keep them out of shared logs. The install token cannot be rotated; if one leaks, re-create the fleet. See Tokens & security.
See Install collectors.
Confirm the rollout
Within about a minute, the collector connects to Telflo and appears as an instance on the fleet's detail page. It pulls its assigned configuration, applies it, and reports the result. Watch its status move through:
| Status | Meaning |
|---|---|
| Pending pickup | The version is assigned, but the collector has not received it yet. |
| Applying | The collector received the version and is applying it. |
| In sync | The collector applied the configuration it was assigned. |
When the collector reports In sync, the configuration you built is running on your collector, delivered remotely. You did not log into the host to edit a file. The setup checklist disappears once the first collector connects. The stats strip at the top of the page summarizes the fleet: collectors, how many are online, version drift, and when the token expires. See Monitor a fleet.
If a collector reports Apply failed, it rejected the configuration. Open the configuration, validate and test it, check the collector's logs on the host, then publish a corrected version and assign it to the deploy group.
Roll out a change and roll back
Updating a fleet follows the same loop as building.
- Edit the configuration and test it.
- Publish the new version.
- On the fleet's Deploy Groups tab, select Edit on the deploy group and choose the new published version.
Collectors move from Pending pickup to Applying to In sync as they pick up the change. Collectors pull from Telflo, so the rollout happens remotely with no change on the hosts. To roll back, assign an earlier published version to the deploy group, and instances converge on it the same way. See Update the configuration.
Next steps
Build
The editor in full: components, configuration, pipelines, and YAML.
Testing
Run sample telemetry through a configuration to check its output.
Fleet management
Deploy, monitor, detect drift, and roll back across many collectors.
AI assistant
Plan, build, and explain configurations from a chat panel in the editor.
Last updated on