OpenTelemetry Collector Builder (OCB) from the UI

CollectorCtrl features a built-in compilation engine powered by the OpenTelemetry Collector Builder (OCB). Infrastructure, Platform, and DevOps teams can assemble, compile, and distribute custom OpenTelemetry Collector binaries directly from the web console without requiring local Go toolchains, compilation dependencies, or container build farms.

Expand

1. Why Build Custom Collector Binaries?

2. Component Discovery via OpenTelemetry Registry

When customizing an OpenTelemetry Collector, you can incorporate any receiver, processor, exporter, extension, or connector developed by the OpenTelemetry project or third-party vendors.

Expand

Version Compatibility Rule

Always ensure that the version tag specified on each Go module (e.g., v0.100.0) matches the OTel Builder Version selected in the configuration form. Mismatches across major OpenTelemetry Collector core revisions may lead to Go module dependency resolution failures during compilation.

3. Build Targets: Main Collector vs. Sidecar

A key capability of CollectorCtrl's Custom Builder is selecting the architectural Build Target:

Build Configuration ──────────────────────────┐
                                              ▼
                                   ┌──────────────────────┐
                                   │  BUILD TARGET FIELD  │
                                   └──────────┬───────────┘
                         ┌────────────────────┴────────────────────┐
                         ▼                                         ▼
              [ 📦 Main Collector ]                       [ 🧩 Sidecar ]
                         │                                         │
                         ▼                                         ▼
            Registered in Package Mgmt:               Registered in Package Mgmt:
            Main Collector Packages                   Sidecar Collector Packages
                         │                                         │
                         ▼                                         ▼
            Assigned as Primary Agent                 Assigned via Localhost Bridge
            Worker across Fleet Nodes                 (:4319) under Supervisor Watchdog

Option A: 📦 Main Collector

• Purpose: Serves as the primary telemetry collection process running on the host or VM.
• Scope: Ingests host-level metrics (hostmetricsreceiver), Windows Event Logs, syslog, and application OTLP traffic (:4317 gRPC / :4318 HTTP).
• Package Destination: Automatically cataloged under Package Management → Main Collector Packages.
• Use Case: Creating a lean, tailored corporate baseline collector containing only your enterprise-approved exporters (e.g., Prometheus, Datadog, Splunk) without the bloat of hundreds of unused Contrib modules.

Option B: 🧩 Sidecar

• Purpose: Serves as an auxiliary, purpose-built collector deployed alongside the main collector on the same host and managed concurrently by the Supervisor daemon.
• Scope: Communicates with the main collector via local in-memory loopback (127.0.0.1:4319) with sub-millisecond latency and zero physical wire egress cost.
• Package Destination: Automatically cataloged under Package Management → Sidecar Collector Packages.
• Use Case: Dedicated vendor migrations (e.g., streaming to Coralogix via coralogixexporter while keeping an existing Splunk agent untouched), SIEM compliance segregation, or LLM token analytics.

4. Build Configuration Parameters

The builder interface provides granular control over compilation flags and binary metadata:

Enforced Baseline Components

To guarantee system stability and compatibility with CollectorCtrl features, the builder automatically enforces two essential components:

• Enforced Receiver (otlpreceiver): Guarantees that the binary can always ingest OpenTelemetry protocol traffic over standard ports (:4317 gRPC / :4318 HTTP) or local loopback (:4319).
• Enforced Exporter (debugexporter): Guarantees that pre-flight syntax checks (otelcol validate) and localized verbose logging can execute without missing exporter errors.

5. End-to-End Build & Deployment Lifecycle

dist:
name: otelcol-custom
description: Enterprise Custom OTel Collector
version: 0.100.0
output_path: /opt/collectorctrl/builds/dist

receivers:
- gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.100.0
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/hostmetricsreceiver v0.100.0

processors:
- gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.100.0
- gomod: go.opentelemetry.io/collector/processor/memorylimiterprocessor v0.100.0

exporters:
- gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.100.0
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/exporter/coralogixexporter v0.100.0

extensions:
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/healthcheckextension v0.100.0

6. Distributables & Registry Management

The Distributables table on the right side of the Custom Builder interface provides an active view of all binaries generated by the builder:

Summary of Best Practices

1. Pin Exact Component Versions: Always specify exact semantic version tags (e.g., v0.100.0) rather than floating @latest tags to ensure build reproducibility.
2. Consult the OTel Registry: Use the OTel Registry ↗ link whenever you need component names, configuration examples, or exporter capabilities.
3. Select Sidecar for Surgical Enhancements: If your primary fleet is already running an established vendor agent (like Splunk or ADOT), build a Sidecar rather than replacing the main agent.
4. Leverage Build Tags for Staging: Tag new builds with tags like canary-test or stage-v1 so you can target them to specific agent groups in Fleet Orchestration before rolling out globally.

Next Steps

• Package Management & Binary Registry — Inspect registered Main and Sidecar packages
• Fleet Orchestration & Policies — Deploy custom binaries via Canary and Coordinated rollouts
• Fleet Overview & Central Control — Inspect active binary versions and process health across nodes
• Upgrade Supervisor Agents — Manage host daemon supervisors under Settings