CollectorCtrlCollectorCtrl Documentation
Welcome to the CollectorCtrl official documentation. CollectorCtrl is a free-to-use, self-hosted control plane for OpenTelemetry Collector fleets, built natively on the industry-standard OpAMP (Open Agent Management Protocol).
CollectorCtrl centralizes collector configuration, health monitoring, versioning, drift detection, and automated binary upgrades across Linux, Windows, macOS, Kubernetes, and Docker without requiring SSH access.
Quick Start in 60 Seconds
The fastest way to evaluate CollectorCtrl is using Docker:
$docker run -d \\
$ -p 4320:4320 \\
$ -p 4321:4321 \\
$ --name collectorctrl \\
$ ghcr.io/collectorctrl/collectorctrl-server:latest
Once running, navigate to http://localhost:4321 and log in with default credentials admin / admin.
For production deployment specs, check the Production Setup Reference.
Documentation Sections
Explore documentation by category:
Getting Started & Architecture
Core concepts, binary distribution architecture, supervisor lifecycle, and OpAMP bidirectional communication.
Read documentationProduction Setup Reference
Deployment topology, systemd & Windows service configs, PostgreSQL setup, and air-gapped fleets.
Read documentationFleet Orchestration & Policies
Label-based policy targeting, progressive canary rollouts, config versioning, and auto-remediation.
Read documentationCustom Binary Builder
Compile custom OpenTelemetry Collector binaries directly from the UI with OCB integration.
Read documentationData Plane Governance
Enforce semantic conventions, log profiling, ClickHouse integration, and telemetry governance.
Read documentationSystem Settings & Security
OIDC SSO integration (Okta/Azure AD/Auth0), RBAC roles, audit logs, and service tokens.
Read documentationCore Platform Architecture
Management Server
The Go-based control plane binary that:
- Serves the React-based Web Dashboard (
port 4321) - Exposes REST API and OpAMP WebSocket Gateway (
port 4320) - Manages fleet state, policies, users, and audit logs in SQLite or PostgreSQL
| Port | Protocol | Purpose |
|---|---|---|
4320 | WebSocket (WSS / WS) | OpAMP Agent communication gateway |
4321 | HTTP / HTTPS | Admin UI Dashboard & REST API |
Supervisor Agent
A lightweight binary deployed alongside OpenTelemetry Collectors on target nodes:
- Process Lifecycle: Supervised start, stop, and restart of collector worker processes
- Config Reconciliation: Supervised config updates with automatic fallback on crash loops
- Drift Auto-Remediation: Constant config hash verification against assigned policy rules
- Self-Upgrades: Zero-downtime remote binary updates with automatic rollback
Key Features & Capabilities
| Feature | Description |
|---|---|
| Guided Onboarding Wizard | Generates tailored install commands for Linux, Windows, K8s, and Docker |
| Honeycomb Fleet Map | Visual grid and table views with live OpAMP status monitoring |
| Dynamic Policy Engine | Rule-based label matching (e.g. env:production, region:us-east) |
| Canary Rollouts | Percentage-based stage rollouts with instant pause and abort buttons |
| Drift Guard | Auto-detects manual configuration edits on remote nodes and auto-remediates |
| OCB Custom Builder | Build lightweight collector binaries with exact receivers and exporters |
| Enterprise SSO & RBAC | OIDC integration for Okta, Azure AD, Auth0, and custom SAML/OIDC providers |
| SIEM Audit Stream | Full audit trail exported via OTLP to Splunk, Datadog, or Elastic |
Community & Support
- GitHub Issues: github.com/CollectorCtrl/CollectorCtrl/issues
- Discussions: Post questions and proposals on GitHub Discussions.
- Security Notifications: Report security issues according to our SECURITY.md guidelines.