Available Components

What is Agent Available Components?

The Agent Available Components feature allows the Bindplane server to know which components are included with a particular distribution of the OpenTelemetry collector and react dynamically based on this knowledge.

How does the Bindplane server know what components are available for a particular distribution?

For v1.x versions of the Bindplane Distribution of OpenTelemetry (BDOT) collector, the list of components is included out-of-the-box with Bindplane. When a v1.x BDOT collector connects to the Bindplane server, it reports its type and version, and the appropriate list of available components can be retrieved.

For v2.x versions of the BDOT collector and other distributions that work with the Bring Your Own Collector feature, the available components will be reported to Bindplane in the initial handshake on collector connection. This is done via the OpAMP AvailableComponents message, utilizing the OpenTelemetry OpAMP extension and OpAMP supervisor.

How does the Bindplane server react based on component availability?

Broadly, the Bindplane server enforces configuration compatibility based on what components are available to a distribution of the OpenTelemetry collector. This is done by checking Bindplane resource requirements and dynamically rendering the configuration.

Checking Bindplane resource requirements

Several checks are made to ensure that a Bindplane configuration isn't sent to a collector that doesn't have the required components.

First, during configuration creation or modification, only resources that have at least one fully compatible telemetry type will be able to be added to the configuration. This can result in certain telemetry types or even full resource types being unavailable for a configuration. The list of available components used to assess compatibility is the list for the latest version of the configuration's associated agent type, and each Bindplane resource includes a list of required OpenTelemetry components for each supported telemetry type.

Example of a partially incompatible resource:

  logs:
    templates:
      - match:
          - component: "github.com/open-telemetry/opentelemetry-collector-contrib/exporter/prometheusremotewriteexporter"
            operator: ">="
            version: "0.0.0"
        exporters: |
          {{ if has "Logs" .telemetry_types }}
          - non_existent:
              region: {{ .region }}
          {{ end }}

  metrics:
    templates:
      - match:
          - component: "github.com/open-telemetry/opentelemetry-collector-contrib/exporter/non_existent"
            operator: ">="
            version: "1.0.0"
          - component: "github.com/open-telemetry/opentelemetry-collector-contrib/exporter/non_existent3"
            operator: ">="
            version: "1.0.0"
        exporters: |
          {{ if has "Metrics" .telemetry_types }}
          - non_existent:
              region: {{ .region }}
          {{ end }}

  traces:
    templates:
      - match:
          - component: "github.com/open-telemetry/opentelemetry-collector-contrib/exporter/non_existent"
            operator: ">="
            version: "1.0.0"
        exporters: |
          {{ if has "Traces" .telemetry_types }}
          - non_existent:
              region: {{ .region }}
          {{ end }}

Example of fully incompatible resource:

  logs:
    templates:
      - match:
          - component: "github.com/open-telemetry/opentelemetry-collector-contrib/exporter/non_existent"
            operator: ">="
            version: "1.0.0"
        exporters: |
          {{ if has "Logs" .telemetry_types }}
          - non_existent:
              region: {{ .region }}
          {{ end }}

  metrics:
    templates:
      - match:
          - component: "github.com/open-telemetry/opentelemetry-collector-contrib/exporter/non_existent"
            operator: ">="
            version: "1.0.0"
          - component: "github.com/open-telemetry/opentelemetry-collector-contrib/exporter/non_existent3"
            operator: ">="
            version: "1.0.0"
        exporters: |
          {{ if has "Metrics" .telemetry_types }}
          - non_existent:
              region: {{ .region }}
          {{ end }}

  traces:
    templates:
      - match:
          - component: "github.com/open-telemetry/opentelemetry-collector-contrib/exporter/non_existent"
            operator: ">="
            version: "1.0.0"
        exporters: |
          {{ if has "Traces" .telemetry_types }}
          - non_existent:
              region: {{ .region }}
          {{ end }}

Second, before sending a configuration to a collector, compatibility is reassessed for a second time to ensure that the collector has all of the required components for the configuration. If it's incompatible, the collector will be put into Incompatible status, and the configuration will not be sent. This is required because while the first check is guaranteed to be accurate for the latest version of the configuration's associated agent type, the second will be accurate for all versions, as long as they have an associated list of available components. An appropriate fix for an Incompatible collector is simply to upgrade the collector to the latest version.

Dynamic configuration rendering

Different versions of the same OpenTelemetry component can require different configuration fields. Common examples of this are when a new feature flag is added or a deprecated feature flag is removed from the component with a new OpenTelemetry release. Since Bindplane configurations are collector version-agnostic, one Bindplane configuration can be rendered differently depending on the available components of the collector that it's paired with. The end result is that a collector should never have an incompatible configuration for a component sent to it and a single Bindplane configuration can be used to support multiple versions of the same component.

Example: the below configuration parameters for the AWS S3 Destination are dependent on the version of the github.com/open-telemetry/opentelemetry-collector-contrib/exporter/awss3exporter component included in the collector. For collectors with a version of the exporter v0.120.0 and older, the Granularity field will be in the config sent to the collector. For collectors with a newer version than that, the Partition Format field will be in the config instead.