OpAMP Control Plane Architecture for OpenTelemetry Fleets

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. Read the architectural rationale: If You Don't Own the Control Plane, You're Not Vendor-Neutral.

1. Interactive System Architecture Flow

Explore the interactive architecture diagram below to understand how the CollectorCtrl Management Server, CollectorCtrl Supervisor, and OpenTelemetry Collector communicate, including network port bindings, protocol directions, and operational capabilities:

System Architecture & Component Interaction

Interactive architectural model of CollectorCtrl Server, Supervisor, and OTel Collector

All ComponentsControl Plane (OpAMP)Data Plane (OTLP)Ports & Network

OpAMP Active

Control PlaneCentral Host

CollectorCtrl Server

Management Control Plane

OpAMP GatewayInbound 4320 (WS)

Web Console & APIInbound 4321 (HTTP)

PostgreSQL / SQLitePort 5432

ws:// :4320

⇄ OpAMP Full Duplex

Host Node BoundaryLinux (systemd) / Windows (Service)

CollectorCtrl Supervisor

Agent Daemon · Outbound Only Connection

0 Inbound Ports

accepts_remote_configreports_effective_configreports_healthaccepts_packagesrollback_watchdog

Process Supervision & Health ProbeLocalhost :13133 (HTTP)

OpenTelemetry Collector

Managed Child Process (Core / Contrib / ADOT / Splunk)

OTLP :4317 / :4318

Receivers (OTLP/Logs)

→

Processors (Batch/Filter)

→

Exporters (Multi-Sink)

OTLP / 443

Telemetry Forwarding

Data PlaneMulti-Sink

Datadog / SplunkHTTPS / HEC

APM, Logs & Metrics

ClickHouse / ElasticOTLP v1.0

Raw Event Storage

Dynatrace / HoneycombOTLP gRPC

Distributed Tracing

💡 Click on any component above to inspect network port specifications, security constraints, and operational capabilities.Selected: CollectorCtrl Supervisor Agent

CollectorCtrl Supervisor Agent

System Service Daemon

Host Daemon & Child Process Lifecycle Supervisor

Lightweight host-level daemon running as a Linux systemd service or Windows Service. It connects outbound to the CollectorCtrl server via OpAMP, watches `/etc/collectorctrl/supervisor.yaml`, performs pre-flight syntax validation, manages child collector processes, and executes rollback if upgrades fail.

Operational Capabilities

• accepts_remote_config: Receives versioned YAML configs
• reports_effective_config: SHA-256 hash tracking
• reports_health: Monitored process watchdog & alerts
• accepts_packages: Remote binary updates with zero SSH
• rollback_watchdog: Auto-reverts if new binary fails health gate

Network Ports & Protocols

Port 13133	TCP / HTTP Localhost probe → OTel Collector · Continuous health check extension polling
Linux Service	/etc/systemd/system/collectorctrl-supervisor.service
Windows Service	CollectorCtrlSupervisor (LocalSystem/Service Account)
Pre-Flight Check	Executes `otelcol validate` before config apply
Memory Footprint	< 35 MB resident set size (RSS)

2. Component Responsibility Matrix

To help enterprise architects and DevOps engineers understand the separation of concerns, the table below outlines the boundaries between each component:

3. Network Ports & Firewall Specifications

Enterprise security teams can lock down networks with minimal exposure: no inbound ports need to be opened on target host nodes.

4. Supervisor Capabilities & Safety Watchdogs

CollectorCtrl implements the OpenTelemetry Agent Management Protocol (OpAMP) with built-in safety gates that prevent malformed configurations or bad binaries from disrupting observability pipelines:

OpAMP Capabilities Implemented

• accepts_remote_config: Allows the CollectorCtrl server to push versioned OpenTelemetry configuration files directly to the agent over the persistent WebSocket channel.
• reports_effective_config: The Supervisor calculates an SHA-256 hash of the currently running configuration and reports it back to the server, enabling instant drift detection and GitOps reconciliation.
• reports_health: Streams continuous health observations (CPU RSS, memory load, process restart counts, and error logs) back to the server every 10 seconds.
• accepts_packages: Enables remote zero-touch binary upgrades without requiring SSH, Ansible, or manual server access.
• accepts_restart_command: Gracefully signals the collector worker process to restart and reload configuration without dropping buffered in-flight data.

Two-Tier Safety Watchdogs

[ Server Pushes New Config ]
             │
             ▼
[ 1. Pre-Flight Syntax Gate ] ───► Fails? ───► Refuse apply, report "Validation Failed", keep running old config
             │ Passes
             ▼
[ 2. Apply & Health Probe ] ────► 13133 fails? ──► Trigger Automatic Rollback to previous working version
             │ HTTP 200 OK
             ▼
[ Report Sync to Dashboard ]

1. Pre-Flight Syntax Validation: Before writing a new YAML configuration to disk, the Supervisor executes otelcol validate in a isolated dry-run container/subprocess. If YAML syntax is invalid, the update is rejected with zero impact to the running collector.
2. Crash-Loop & Rollback Watchdog: When upgrading collector or supervisor binaries, the Supervisor starts a monitored probation timer. If the new binary fails to reach HTTP 200 on the health check endpoint (port 13133) or fails to establish an OpAMP connection within 60 seconds, it automatically reverts to the previous known-good binary.

5. 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 dedicated Service Account:

• Spawns and supervises otelcol-contrib.exe as a child process using Windows Job Objects for resource containment.
• Captures local system performance counters and Windows Event Logs (wineventlog).

🐧 Linux Infrastructure Deployment (systemd Daemon)

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

• Monitors the process tree health and supervises stdout/stderr log output.
• Enforces Linux cgroups v2 resource limits to cap CPU and memory consumption.

☸️ Kubernetes Workload Observation (pilot)

For collectors you already deploy to Kubernetes with Helm, GitOps or your own pipeline:

• Observer: One CollectorCtrl observer per cluster watches CollectorMonitor resources. Each monitor selects one Deployment, DaemonSet or StatefulSet and its collector container.
• Read-only by design: The observer reads workloads, pods and mounted ConfigMaps through the Kubernetes API and reports a snapshot over a trusted wss:// OpAMP connection. It never modifies workloads or ConfigMaps; your deployment system keeps control.
• Separate from host management: Observed workloads appear in their own Fleet view and are excluded from host policies, canaries, Supervisor upgrades and host-only actions.

See Kubernetes Workload Observation for installation and current limits.

6. Enterprise Security & Governance

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