v1.1.10Free-to-use OpAMP fleet management for Windows & LinuxDownload →
Download

CollectorCtrl Documentation

Welcome to the CollectorCtrl documentation. CollectorCtrl is a free-to-use, self-hosted management platform for OpenTelemetry Collector fleets, built on the industry-standard OpAMP (Open Agent Management Protocol).

What is CollectorCtrl?

If you run OpenTelemetry Collectors on more than a handful of nodes, you have probably felt the pain:

  • SSH-ing into servers to edit YAML configs
  • Forgetting which collector version runs where
  • Manual restarts causing telemetry gaps
  • No visibility into which agents are healthy

CollectorCtrl solves this by giving you a central control plane for your entire collector fleet. You install a lightweight Supervisor agent on each node, and it handles configuration, health reporting, and upgrades automatically — all over a secure WebSocket connection.

Quick Start

The fastest way to try CollectorCtrl is with Docker:

bash
$docker run -d \\
$  -p 4320:4320 \\
$  -p 4321:4321 \\
$  --name collectorctrl \\
$  ghcr.io/collectorctrl/collectorctrl-server:latest

Then open http://localhost:4321 and log in with admin / admin.

For production setups, see the Setup & Installation Guide.

Core Concepts

Management Server

The brain of the operation. A single Go binary that:

  • Serves the React-based Admin UI dashboard
  • Exposes a REST API for programmatic access
  • Runs the OpAMP WebSocket gateway for agent communication
  • Stores fleet state, policies, users, and audit trails in SQLite or PostgreSQL

Default ports:

PortPurpose
4320OpAMP WebSocket (agent communication)
4321Admin UI & REST API

Supervisor Agent

A lightweight agent that runs on each target node alongside your OpenTelemetry Collector:

  • Process Lifecycle: Starts, stops, and restarts the OTel Collector process
  • OpAMP Client: Maintains a persistent secure WebSocket to the Management Server
  • Config Reconciliation: Receives configuration updates and applies them via hot-reload
  • Drift Guardian: Detects manual config file changes and reverts them to the authorized version
  • Self-Upgrades: Downloads and installs new supervisor versions with automatic rollback on failure

The Supervisor runs as a native Windows Service or Linux systemd daemon.

Collector

The standard OpenTelemetry Collector binary — whether that's OTel Core, OTel Contrib, a vendor distribution, or a custom binary built with the OCB Builder. The Supervisor manages this process as a child worker.

Feature Overview

FeatureDescription
Fleet DashboardHoneycomb grid and table views with real-time health status
Dynamic PoliciesLabel-based targeting (e.g., env:production) for config rollouts
Canary RolloutsDeploy to a percentage of your fleet before full promotion
Config VersioningEvery policy change is versioned with full history
Drift PreventionSupervisor automatically reverts unauthorized local changes
Hot-ReloadConfig updates without collector restarts (SIGHUP on Linux, API reload on Windows)
Remote UpgradesFleet-wide supervisor upgrades with queue-based rate limiting and auto-rollback
RBAC & SSORole-based access control with OIDC integration (Okta, Azure AD, Auth0)
Audit LoggingImmutable record of all actions, streamable via OTLP to SIEM
API TokensService account tokens for CI/CD and automation
OCB BuilderBuild custom OpenTelemetry Collector binaries from the UI
Package RepositoryStore and version your collector binaries
Semantic RegistryMap vendor-specific fields to standard OTel schemas
Telemetry GovernorProfile logs and traces with ClickHouse integration

Documentation Sections

Getting Help