builder

OpenTelemetry Collector Builder (ocb)

This program generates a custom OpenTelemetry Collector binary based on a given configuration.

TL;DR

$ go install go.opentelemetry.io/collector/cmd/builder@v0.129.0
$ cat > otelcol-builder.yaml <<EOF
dist:
  name: otelcol-custom
  description: Local OpenTelemetry Collector binary
  output_path: /tmp/dist
exporters:
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/exporter/alibabacloudlogserviceexporter v0.129.0
  - gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.129.0

receivers:
  - gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.129.0

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

providers:
  - gomod: go.opentelemetry.io/collector/confmap/provider/envprovider v1.35.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.35.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/httpprovider v1.35.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/httpsprovider v1.35.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/yamlprovider v1.35.0
EOF
$ builder --config=otelcol-builder.yaml
$ cat > /tmp/otelcol.yaml <<EOF
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: localhost:4317

exporters:
  debug:

service:
  pipelines:
    traces:
      receivers:
      - otlp
      exporters:
      - debug
EOF
$ /tmp/dist/otelcol-custom --config=/tmp/otelcol.yaml

Installation

There are three supported ways to install the builder:

1. Via official release Docker images (recommended)
2. Via official release binaries (recommended)
3. Through go install (not recommended)

Official release Docker image

You will find the official docker images at DockerHub.

Pull the image via tagged version number (e.g. 0.129.0) or 'latest'. You may also specify platform, although Docker will handle this automatically as it is a multi-platform build.

docker pull otel/opentelemetry-collector-builder:latest

The included builder configuration file/manifest should be replaced by mounting a file from your local filesystem to the docker container; the default location is /build/builder-config.yaml. If you mount a file at a different location inside the container, your builder.config.yaml must be specified as a command line argument to ocb. Additionally, the output folder must also be mounted from your local system to the docker container. This output directory must be specified in your builder-config.yaml file as it cannot be set via the command-line arguments.

Assuming you are running this image in your working directory, have a builder-config.yaml file located in this folder, the dist.output_path item inside your builder-config.yaml is set to ./otelcol-dev, and you wish to output the binary/go module files to a folder named output, the command would look as follows:

docker run -v "$(pwd)/builder-config.yaml:/build/builder-config.yaml" -v "$(pwd)/output:/build/otelcol-dev" otel/opentelemetry-collector-builder:latest --config=/build/builder-config.yaml

Please note that a --config flag must be passed to specify your custom manifest.yaml/builder-config.yaml file regardless of where you mount it inside the container, otherwise a default config is used that cannot be changed.

Additional arguments may be passed to ocb on the command line as specified below, but if you wish to do this, you must make sure to pass the --config argument, as this is specified as an additional CMD, not an entrypoint.

Official release binaries

This is the recommended installation method for the binary. Download the binary for your respective platform from the "Releases" page.

go install

You need to have a go compiler in your PATH. Run the following command to install the latest version:

go install go.opentelemetry.io/collector/cmd/builder@latest

If installing through this method the binary will be called builder.

In order to successfully generate and build a collector using ocb, you must use compatible Go version.

Running

A build configuration file must be provided with the --config flag. You will need to specify at least one module (extension, exporter, receiver, processor) to add to your distribution. To build a default collector configuration, you can use this build configuration.

ocb --config=builder-config.yaml

Use ocb --help to learn about which flags are available.

Debug

Debug symbols

By default, the LDflags are set to -s -w, which strips debugging symbols to produce a smaller OpenTelemetry Collector binary. To retain debugging symbols and DWARF debugging data in the binary, override the LDflags as shown: