Fleet: manage collectors from the app

Fleet lets you change what many collectors send, from one place, with versions, a preview, a rollout view and a one-click rollback. It manages the Logthread Agent and any OpenTelemetry Collector run under the OpAMP Supervisor. Use it when you have more than a few machines and do not want to edit YAML on each one.

You need the member role to look at Fleet, and the admin role to create, edit, activate or roll back a config. Open Fleet in the app.

How it works#

1. An agent started in Fleet mode connects to Logthread over wss://<endpoint>/v1/opamp, authenticated with its ingest key. It appears under Fleet → Agents with its health, labels and version.
2. You write a config: collector YAML plus a selector on labels, such as env=prod and role=web.
3. You activate a version of the config. Logthread pushes it to every connected agent whose labels match.
4. The agent merges the pushed config on top of its local profiles, applies it and reports back. Rollout shows each agent as in sync, applying, pending or failed.

The supervisor config the agent generates never contains your ingest key, and a Fleet config cannot contain one either: see the rules below.

Connect an agent#

Open Fleet → Install, choose an install method and copy the command. With the Logthread Agent on Linux:

curl -sSL https://downloads.logthread.com/agent/install.sh | sudo sh -s -- \
  --key YOUR_INGEST_KEY --profiles linux-host --fleet --labels env=prod,role=web

On Windows add -Fleet -Labels env=prod,role=web to install.ps1, and in a container set LOGTHREAD_FLEET=true. The labels you give are what selectors match, together with attributes the agent reports itself (host.name, os.type, service.name, service.version). The Install tab also shows how to run a stock OpenTelemetry Collector under the OpAMP Supervisor, and the status-only alternative: an agent with the fleet-readonly profile reports its health and effective config but cannot be changed from Logthread.

An agent that does not accept remote config is listed but cannot be managed. An agent counts as connected while it has sent a heartbeat in the last 90 seconds. Filter by Connected, Disconnected, Unhealthy or Failed, search by name or label, and open an agent to see its health, its Effective config and a Diff against what Logthread wants it to run.

Write a config#

Choose Fleet → Configs → New config. Start from a template:

Then set a Name, a Selector (the labels an agent must have; an empty selector matches every agent) and a Priority. Creating a config makes version 1 and does not activate it: nothing is pushed until you activate.

A config is checked every time you save a version:

• the YAML must parse, be 256 KB or smaller and use only these top-level keys: receivers, processors, exporters, extensions, connectors, service;
• service.pipelines must define at least one pipeline with receivers and exporters, and every component a pipeline names must be defined;
• it must not contain a literal ingest key. Reference it as ${env:LOGTHREAD_INGEST_KEY}, and the endpoint as ${env:LOGTHREAD_ENDPOINT};
• you get a warning, not an error, when no OTLP exporter sends to Logthread, because agents using that config would not reach this workspace.

Use the snake_case component names of the current agent (otlp_http/logthread, file_log, host_metrics). Maps merge with the local profiles and lists are replaced, so a pushed pipeline with the same name as a profile's pipeline replaces its component lists.

Limits: 50 configs per workspace, a name of 1 to 64 characters, at most 16 selector entries, and a priority from -1000 to 1000.

Which config an agent gets#

An agent gets the active version of the highest-priority enabled config whose selector matches all its labels. On equal priority the older config wins. With no match, the agent keeps running its local profiles. A config that has no active version, or that you disabled, is never assigned. An agent matched by a higher-priority config shows as shadowed in the lower one's rollout.

Roll out and roll back#

1. Open the config, edit the YAML and choose Save new version. Add a note: it is shown in the version list. Saving does not change any agent.
2. In the version list choose Activate on the version you want. A dialog shows the diff against the current version first.
3. Watch Rollout: each matching agent moves from pending to applying to in sync, and a failed one shows the error it reported.
4. To undo, choose Roll back on an earlier version. A rollback is the same push of an older, valid version and is recorded in the audit log as a rollback.

Every version is kept. You can disable a config to stop pushing it, and delete a config only while it has no active version.

From CI or an AI agent#

An API key with the fleet scope can create configs and activate them through the MCP tools create_fleet_config and activate_fleet_config, and any key can read them with list_fleet. They act as the person who created the key, within that person's role, and each change is audited. See AI agents (MCP).

Troubleshooting#

Next: see what the agents send in Explore.