Build and Connect Custom OpenTelemetry Collector Distributions

This guide will walk you through the process of creating a custom OpenTelemetry distribution and how to use it with Bindplane.

Bindplane works best with the Bindplane Collector which is built using OpenTelemetry Collector Contrib. However, with the introduction of tools like the OpenTelemetry Collector Builder (OCB), OpenTelemetry Distribution Builder, and OpenTelemetry OpAMP Supervisor a custom built collector can be used seamlessly with Bindplane.

This guide is divided into a series of steps. You will ultimately learn how to connect your custom OpenTelemetry Collector distribution to Bindplane.

Prerequisites

• Reading the BYOC Feature Guide before hand will provide valuable context about what is involved and what features will be available.

• A public GitHub repository your distribution will be hosted in.

• Organization admin access to your Bindplane instance.

1. Building your OpenTelemetry Collector Distribution

To build your OpenTelemetry Collector Distribution, this guide will use the OpenTelemetry Distribution Builder tool. This involves creating a GitHub Actions workflow file for the distribution builder tool and an OCB manifest that defines what components your collector is built with.

The distribution builder will package the OpAMP Supervisor into the release artifact. Once you create your Agent Type in Bindplane, this allows Bindplane to generate an installation command that will connect your collector to it.

You can include whichever components you want in your OCB manifest. This could be any component from OpenTelemetry Collector Core, OpenTelemetry Collector Contrib, the Bindplane Distribution for the OpenTelemetry Collector, any other distribution, or even your own custom components.

However there are a few components that are necessary to be included in your manifest in order to be minimally compatible with Bindplane. The following OCB manifest can be used as a starting point for your own to ensure you have the required components.

NOTE

You'll likely want to update the versions to their latest versions. For Bindplane components, this will be the same version as the latest BDOT version, found here.

# A skeleton OCB manifest that contains the minimal collector components needed to be compatible with Bindplane.
dist:
  module: #todo
  name: #todo
  description: #todo
  output_path: #todo
  version: #todo
conf_resolver:
  default_uri_scheme: "env"
connectors:
  - gomod: go.opentelemetry.io/collector/connector/forwardconnector v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/connector/routingconnector v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/connector/failoverconnector v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/connector/roundrobinconnector v0.128.0
  # Add additional connectors here

exporters:
  - gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.128.0
  - gomod: go.opentelemetry.io/collector/exporter/otlphttpexporter v0.128.0
  - gomod: go.opentelemetry.io/collector/exporter/nopexporter v0.128.0
  # Add additional exporters here

extensions:
  - gomod: github.com/observiq/bindplane-otel-collector/extension/bindplaneextension v1.79.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/healthcheckextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/storage/filestorage v0.128.0
  # Add additional extensions here

processors:
  - gomod: github.com/observiq/bindplane-otel-collector/processor/snapshotprocessor v1.79.0
  - gomod: github.com/observiq/bindplane-otel-collector/processor/throughputmeasurementprocessor v1.79.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/metricstransformprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/transformprocessor v0.128.0
  # Add additional processors here

receivers:
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/filelogreceiver v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/hostmetricsreceiver v0.128.0
  - gomod: go.opentelemetry.io/collector/receiver/nopreceiver v0.128.0
  # Add additional receivers here

providers:
  - gomod: go.opentelemetry.io/collector/confmap/provider/envprovider v1.34.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.34.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/httpprovider v1.34.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/httpsprovider v1.34.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/yamlprovider v1.34.0
  # Add additional providers here

replaces:
  - github.com/observiq/bindplane-otel-collector/internal/version => github.com/observiq/bindplane-otel-collector/internal/version v0.0.0-20250306153219-6fe3f849c29f  # Needed for Bindplane Extension
  # Add additional replaces here

With the manifest defined, the action workflow for the OpenTelemetry Distro Builder will need to be created next. The following is an example workflow that can be built on. This example uses matrixing to improve performance building for multiple platform/architecture pairs.

name: Matrixed OpenTelemetry Distribution Build

on:
  push:
    tags:
      - "v*" # Runs when a version tag is pushed (e.g., v1.0.0)
  workflow_dispatch: # Enables manual triggering from the GitHub UI

permissions:
  contents: write # This is required for creating/modifying releases

jobs:
  build:
    # Configure build matrix to run multiple platform builds in parallel
    strategy:
      matrix:
        # Define the platforms we want to build for
        platform: [linux/amd64, linux/arm64, darwin/arm64, windows/amd64]
        # Map platform identifiers to simpler names for artifact handling
        include:
          - platform: linux/amd64
            os: linux
            arch: amd64
            artifact_name: linux-amd64
          - platform: linux/arm64
            os: linux
            arch: arm64
            artifact_name: linux-arm64
          - platform: darwin/arm64
            os: darwin
            arch: arm64
            artifact_name: darwin-arm64

          - platform: windows/amd64
            os: windows
            arch: amd64
            artifact_name: windows-amd64
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Build the OpenTelemetry distribution for each platform
      - name: Build and Package
        uses: observiq/otel-distro-builder@main
        with:
          os: ${{ matrix.os }}
          arch: ${{ matrix.arch }}

      # Upload platform-specific artifacts with a unique name
      # These artifacts are available for download in the GitHub Actions UI
      - name: Upload Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: distribution-artifacts-${{ matrix.artifact_name }}
          path: |
            ${{ startsWith(matrix.platform, 'linux') && format('{0}/artifacts/*.deb', github.workspace) || '' }}
            ${{ startsWith(matrix.platform, 'linux') && format('{0}/artifacts/*.rpm', github.workspace) || '' }}
            ${{ startsWith(matrix.platform, 'linux') && format('{0}/artifacts/*.apk', github.workspace) || '' }}
            ${{ startsWith(matrix.platform, 'windows') && format('{0}/artifacts/*.zip', github.workspace) || '' }}
            ${{ (startsWith(matrix.platform, 'linux') || startsWith(matrix.platform, 'darwin')) && format('{0}/artifacts/*.tar.gz', github.workspace) || '' }}
            ${{ format('{0}/artifacts/*.sbom.json', github.workspace) || '' }}
            ${{ format('{0}/artifacts/*_checksums.txt', github.workspace) || '' }}
          retention-days: 5 # Artifacts are kept for 5 days then automatically deleted

  # Create a single release containing all platform artifacts
  release:
    needs: build # Wait for all platform builds to complete
    runs-on: ubuntu-latest
    permissions:
      contents: write # Required permission for creating releases
    steps:
      # Download all platform-specific artifacts into a single directory
      - name: Download All Artifacts
        uses: actions/download-artifact@v4
        with:
          path: all-artifacts
          pattern: distribution-artifacts-* # Match all our platform-specific artifacts
          merge-multiple: true # Combine all artifacts into a single directory

      # Create a GitHub Release and attach all platform artifacts
      # This makes all platform builds available for download from the Releases page
      - name: Create Release
        uses: softprops/action-gh-release@v2
        with:
          files: all-artifacts/**/*

The workflow can be manually triggered, and is automatically triggered every time a tag is pushed. Using a tag is the recommended approach. Make sure to increment the version in the OCB manifest as well.

2. Creating an Agent Type in Bindplane

In Bindplane, an Agent Type is used to represent an OpenTelemetry Collector Distribution. For example, the BDOT v1 and v2 collectors are both Agent Types.

With a GitHub repository set up for your distribution, we can create an Agent Type resource and apply it to Bindplane using the CLI. The following is an example Agent Type resource defined in a YAML file.

apiVersion: bindplane.observiq.com/v1
kind: AgentType
metadata:
  name: custom-otel-collector
  displayName: Custom OTel Collector
  description: A custom built OTel collector with Bindplane components.
spec:
  repositoryLink: https://github.com/user/custom-collector
  platformArchSet:
    - platform: darwin
      arch: arm64
    - platform: linux
      arch: amd64
    - platform: linux
      arch: arm64
    - platform: windows
      arch: amd64

You'll want to create your own Agent Type resource in a YAML file with these values set. Crucially the metadata.name value needs to match the value of dist.name in your OCB manifest.

With the Agent Type resource file created, you can use the CLI to give it to Bindplane using the following command:

bindplane apply -f /path/to/agent/type/file.yaml

See the Bring Your Own Collector documentation for more information about this step.

3. Version Syncing

With the Agent Type created in Bindplane, it will periodically check the repository to see if there is a new release available. This enables Bindplane to generate an install command for your collector distribution using generic installation scripts. By default, this syncing occurs once every hour. However, with a newly created Agent Type, we'll trigger an initial syncing.

First, make sure you've ran the OpenTelemetry Distro Builder at least once in your repo and have a collector release available. Then run the following command using the Bindplane CLI (replace <your_agent_type> with your Agent Type's name):

bindplane sync agent-versions --agent-type <your_agent_type>

After this successfully runs, you'll be able to install the latest release of your distribution from within Bindplane.

4. Configuration Building

Creating an Agent Type for your distribution also streamlines building configurations. To get the most out of this functionality, you'll want to make sure you have connected a custom collector distribution to Bindplane and it has reported its Available Components. For more information on Available Components, see this feature guide.

When creating a configuration, you can select your Agent Type from the dropdown. This labels the configuration accordingly and filters available resources to only those supported by your distribution. When adding sources, any that rely on OpenTelemetry components missing from your manifest will appear as Incompatible. This ensures you don’t deploy a configuration your collector can’t run, preventing errors.