System Architecture & Philosophy

CollectorCtrl is built on the principle of Absolute Fleet Governance. By providing a vendor-neutral, self-hosted control plane, it decouples the management of OpenTelemetry from your underlying host environments and proprietary vendor distributions.

Technical Architecture Overview

The CollectorCtrl architecture is comprised of a central controller (Main) communicating with distributed agents (Supervisors) over a secure, bidirectional WebSocket protocol derived from the OpenTelemetry Agent Management Protocol (OpAMP) standard.

System Architecture Overview

1. The Core Problem: The "Collector Deficit" & Vendor Lock-In

Most enterprise observability organizations rely on vendor-customized OpenTelemetry distributions (e.g. AWS Distro for OTel [ADOT], Splunk OTel, Dynatrace OTel, etc.). While optimized for their respective SaaS backends, these proprietary distributions introduce critical engineering issues:

Component Deficits: Exporters and processors that route metrics or traces to competing backends are purposefully compiled out of specific vendor binaries to enforce platform stickiness.
Semantic Fragmentation: There is no uniform consensus on semantic conventions. Vendor A requires service.name inside resource attributes, Vendor B requires service_name in headers, and Vendor C parses application. Alert rules and telemetry dashboards break during migrations.
Management Silos: Fleet operations become locked into vendor-specific SaaS dashboard portals, precluding an unified, on-prem dashboard for multi-cloud deployments.

The CollectorCtrl Solution

We decouple the management plane from the data routing plane. The CollectorCtrl Supervisor manages any compiled OTel binary, granting your infrastructure teams the freedom to swap out collector binaries, route telemetry streams to parallel destinations, and apply semantic mappings on the edge before data ingestion occurs.

2. Supervisor Lifecycle & OpAMP Communication

The Supervisor Agent operates as a long-running system daemon. When initialized, the Supervisor establishes a secure, persistent TCP connection to the Main OpAMP gateway.

Bidirectional Registration Flow

Handshake & Identification: The Supervisor sends a JSON/gRPC agent identification package detailing its hostname, CPU architecture, OS version, active network interfaces, and a cryptographic hash of its active OTel configuration.
Authentication: The gateway validates the client connection using a pre-shared organization API token or local mTLS certificates.
Heartbeat Loop: Every 10 seconds, the agent transmits a heartbeat carrying lightweight performance metrics (Memory consumption, CPU load, process status) and logs.
Dynamic Pull/Push: When an administrator publishes a policy update on the Main Console, the Gateway flags the target Supervisors to download the new versioned YAML payload. The Supervisor writes the file to its internal staging path, runs a dry-run validate command (otelcol validate --config config.yaml), and triggers a hot-reload.

3. Deployment Philosophy Across OS Platforms

Telemetry structures vary heavily depending on the host operating system. CollectorCtrl supports three primary distribution designs:

A. Windows Enterprise Deployment (Native Service)

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

Binary Execution: It spawns and manages otelcol.exe (or a vendor-equivalent executable) as a child process.
Process Isolation: The supervisor intercepts Windows Event Logs directly and forwards them to the Collector's local pipeline endpoints using loopback UDP or Named Pipes.

B. Linux Infrastructure Deployment (systemd Daemon)

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

Process Lifecycle: It monitors the system process tree, capturing stdout/stderr from otelcol and piping it directly to the local telemetry observations stream.
Local Hardening: Utilizes standard Linux cgroups to throttle memory and CPU usage of the managed collector sidecar.

C. Kubernetes Cluster Integration (Pod Sidecar / DaemonSet)

For containerized Kubernetes workloads, CollectorCtrl can be deployed via a unified Helm Chart:

DaemonSet Approach: A single Supervisor runs on each node, capturing kubelet container metrics and forwarding them to local collector nodes.
Sidecar Injection: The Supervisor and OTel Collector are injected alongside application containers within a single pod. The Supervisor watches a shared volume mount containing dynamic configurations pushed from the Main Server.

4. Self-Hosted Governance & Security

CollectorCtrl is strictly self-hosted. Unlike SaaS alternatives, your configuration files, system credentials, API tokens, database schemas, and private telemetry data never leave your internal boundary.

[!IMPORTANT] Because CollectorCtrl resides entirely inside your network, it integrates directly with internal enterprise components:

Active Directory & OIDC Identity Providers (SSO)

Private PostgreSQL clusters

Local SMTP mail relays for alert routing

On-premise SIEM systems (Splunk, Elastic, Sentinel) using OTLP Audit Logs