BetaFree-to-use OpAMP fleet management for Windows & LinuxDownload →
Download

System Architecture & Philosophy

CollectorCtrl is built on the core principle of Absolute Fleet Governance. By providing a vendor-neutral, self-hosted control plane, it decouples OpenTelemetry collector management from proprietary vendor SaaS lock-in and host OS environments.

Vendor-Neutral Control Plane

CollectorCtrl decouples the management plane from the data routing plane. The Supervisor manages any compiled OTel binary (Core, Contrib, ADOT, Splunk, Dynatrace, or custom OCB builds), granting infrastructure teams complete freedom to swap out binaries and route telemetry to parallel destinations.

1. Technical Architecture Overview

The CollectorCtrl architecture consists of a central controller communicating with distributed agents (Supervisors) over a secure, bidirectional WebSocket protocol built on the OpenTelemetry Agent Management Protocol (OpAMP) specification.

OpAMP WebSocket Gateway

Persistent bidirectional control channel for state synchronization, policy delivery, and health heartbeats.

Lightweight Supervisor Agent

Runs on each node as a systemd unit or Windows Service, managing the child OTel collector process lifecycle.

Self-Hosted Central Storage

Stores fleet inventory, policy versions, audit logs, and user roles in SQLite or high-concurrency PostgreSQL.

2. Solving the "Collector Deficit"

Most enterprise observability organizations rely on vendor-customized OpenTelemetry distributions. While optimized for specific SaaS backends, these proprietary distributions introduce critical engineering issues:

  • Component Deficits: Exporters and processors routing metrics to competing backends are purposefully excluded from specific vendor binaries.
  • Semantic Fragmentation: Inconsistent field names (e.g. service.name vs service_name vs application) break dashboards and alerting rules during vendor migrations.
  • Management Silos: Fleet operations become locked into vendor-specific SaaS dashboard portals.

The CollectorCtrl Solution

CollectorCtrl grants infrastructure teams complete governance over data pipelines:

  • Swap out collector binaries across the fleet without SSH access.
  • Apply semantic attribute transformations on the edge before ingestion.
  • Multi-destination routing: stream telemetry simultaneously to Datadog, Splunk, ClickHouse, and OTLP storage.

3. Supervisor Lifecycle & OpAMP Communication

The Supervisor Agent operates as a long-running system daemon. When initialized, the Supervisor establishes a secure, persistent connection to the central OpAMP gateway (port 4320).

1

1. Handshake & Identification

The Supervisor transmits an agent identification payload containing hostname, CPU architecture, OS version, active network interfaces, and effective config hash.

2

2. Client Authentication

The gateway authenticates the client using an organization API token or local mTLS certificates.

3

3. Continuous Heartbeat Loop

Every 10 seconds, the agent transmits a heartbeat carrying CPU load, memory usage, process status, and log observations.

4

4. Dynamic Policy Reconciliation

When policy changes are published in the UI, the Gateway flags the target Supervisors to pull the new versioned YAML payload. The Supervisor applies the configuration with a supervised restart and reports the applied hash back to the server.

4. Cross-Platform OS Deployment Models

🏢 Windows Enterprise Deployment (Native Windows Service)

On Windows Server hosts, the Supervisor installs as a native Windows Service (CollectorCtrlSupervisor.exe) under LocalSystem or a custom Service Account:

  • Spawns and supervises otelcol.exe as a child worker process.
  • Captures local system metrics and Windows Event Logs.

🐧 Linux Infrastructure Deployment (systemd Daemon)

On Linux servers (Ubuntu, RHEL, Debian, Amazon Linux), the Supervisor runs as a systemd unit (collectorctrl-supervisor.service):

  • Monitors process tree health and stdout/stderr log output.
  • Enforces cgroups resource limits to throttle CPU and memory consumption.

☸️ Kubernetes Cluster Integration (Pod Sidecar / DaemonSet)

For containerized Kubernetes workloads:

  • DaemonSet: Runs one Supervisor per node, gathering kubelet container metrics.
  • Pod Sidecar: Injected alongside application pods, watching shared volume mounts for config updates.

5. Enterprise Security & Governance

CollectorCtrl is 100% self-hosted. Your configuration files, credentials, API tokens, database schemas, and telemetry payloads never leave your network boundary.

Enterprise Security Integrations
  • SSO Authentication: OIDC integration for Okta, Azure AD, Auth0, and Ping Identity.
  • Audit Logging: Immutable audit logs exported via OTLP to Splunk, Elastic, or SIEM backends.
  • Air-Gapped Operation: Built-in package mirror mode eliminates external internet dependencies.