Bring Your Own Collector

IMPORTANT

Bring Your Own Collector is a Bindplane Enterprise Edition feature.

What is Bring Your Own Collector?

Bring Your Own Collector (BYOC) is a feature for Bindplane Enterprise Edition that facilitates using your own OpenTelemetry Collector distribution with Bindplane. Bindplane will recognize a new collector when it connects, understand which components it contains, and customize the experience for that specific collector distribution.

Creating a distribution

The first step towards using BYOC is creating your own distribution. This can be done in a variety of ways, but the recommended approach is using the OpenTelemetry Distribution Builder (OCB). This is a tool developed by Bindplane to streamline the process of creating, managing, and distributing your own OpenTelemetry Collector. The OCB takes an OpenTelemetry Collector Builder manifest and creates a GitHub release of the collector built from the manifest for the specified platforms.

Creating an Agent Type

Once you have created your own distribution it's time to create an Agent Type in Bindplane. This is how Bindplane interprets different distributions of the OpenTelemetry Collector. For example, the v1 and v2 BDOT Collectors are both Agent Types in Bindplane. There are a couple options for creating an Agent Type in Bindplane.

OpAMP

If you connect one of your custom collector types to Bindplane, it will create a basic Agent Type based on the information reported by the collector via OpAMP. This Agent Type doesn't have all the information needed for additional functionality like version syncing, but it is enough to get going. You will be able to create configurations tailored to this distribution and the OTEL components it was built with.

API

Using the API to create your Agent Type is the recommended method so Bindplane can get all the information it needs. This will unlock version syncing, collector installation scripts, and platform support.

NOTE

If the OpAMP approach was used to create the initial Agent Type, the API can be used to update it with additional information to enable full functionality.

You'll want to create a YAML file to define your Agent Type. Below is an explanation of the parameters and an explanation.

Parameter	Description
apiVersion	The API version of the resource being used. This should always be bindplane.observiq.com/v1.
kind	Tells Bindplane what kind of resource it is dealing with. This should always be AgentType.
metadata.name	This is a unique identifier for your Agent Type. This value is reported by the collector via OpAMP and can be found in the manifest used to build your collector. In the manifest file it is the parameter dist.name.
metadata.displayName	A friendly, readable name for your Agent Type.
metadata.description	A description of your Agent Type to provide additional information.
spec.repositoryLink	The link to the GitHub repository your collector distribution lives in. This is needed for version syncing and agent installation.
spec.platformArchSet	An array of platforms and architectures that your distribution supports. This is needed for version syncing, agent installation, and creating configurations of a given platform.

apiVersion: bindplane.observiq.com/v1
kind: AgentType
metadata:
  name: custom-otel-collector
  displayName: Custom OTel Collector
  description: A custom OTel collector used for just sending host metrics to an OTLP endpoint.
spec:
  repositoryLink: https://github.com/owner/CustomCollector
  platformArchSet:
    - platform: darwin
      arch: arm64
    - platform: linux
      arch: amd64
    - platform: windows
      arch: amd64

You can apply this Agent Type to Bindplane using the CLI like so:

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

You'll need to make sure the API key used to make this request has permission to create an Agent Type (requires organization admin permission).

Using your Distribution in Bindplane

Once an Agent Type for your collector distribution is created, functionality for supporting your distribution is unlocked in Bindplane.

Version Syncing

NOTE

Offline Agent Upgrades do not support BYOC versions today.

The repository link for your collector distribution needs to be defined in your Agent Type. This is so Bindplane knows which repository to pull releases from. Additionally a complete list of platform-architecture pairs supported by your distribution needs to be defined so Bindplane knows which artifacts it should remember.

This enables Bindplane to periodically check your repository for new releases of your distribution. Alternatively if a new version of your collector connects to Bindplane that it doesn't recognize it will dynamically check for any new releases.

All of this facilitates using Bindplane's generic installation scripts to easily install a new collector and have it connect to Bindplane. This process is very similar to the installation support provided for v1 and v2 of the BDOT collector.

Generic Installation

The generic installation scripts are designed to be used with release artifacts built using the OCB. Bindplane will generate a command similar to installing a v1 or v2 BDOT collector that will invoke the generic install script, download the release, install the collector, and connect it to Bindplane. This streamlines the installation process and gets you up and running with your collector distribution.

Configuration Building

Another aspect of BYOC is creating a configuration. The resources available in Bindplane are built on top of OpenTelemetry components (receivers, exporters, processors, etc). The underlying components are all available in the BDOT collector, however there is no guarantee for this with custom distributions. Instead, Bindplane keeps track of what components a distribution was built with and uses this information when building a configuration. The configuration is tagged for a specific Agent Type and the resources available to use are restricted to what components the distribution was built with. When selecting agents to apply the configuration to, only those of a matching Agent Type are shown as options.

Available Components

Enabling the Agent Available Components feature is easy for BYOC.

1. It's assumed that your collector has been built with the OpAMP extension, and is connected to Bindplane via the OpAMP supervisor.

2. Ensure that the correct capability has been configured for both the extension and the supervisor. For both of these, the YAML configuration should have this flag set:

capabilities:
  reports_available_components: true

NOTE

If you use the generic installation scripts for installing your collector, this capability will already be enabled in the supervisor configuration.

That's it! Your collector should now be set up to report its available components to Bindplane over OpAMP.