Compilar um Collector personalizado com o OpenTelemetry Collector Builder

O OpenTelemetry Collector possui cinco distribuições oficiais que vêm pré-configuradas com certos componentes. Se você precisar de mais flexibilidade, pode usar o OpenTelemetry Collector Builder (ou ocb) para gerar um binário personalizado da sua própria distribuição que inclua componentes personalizados, componentes upstream e outros componentes disponíveis publicamente.

O guia a seguir mostra como começar a usar o ocb para compilar seu próprio Collector. Neste exemplo, será criada uma distribuição do Collector voltada para o desenvolvimento e teste de componentes personalizados. É possível iniciar e depurar (debug) os componentes do Collector diretamente no ambiente de desenvolvimento integrado (IDE) de sua preferência para Golang. Utilize todos os recursos de depuração da sua IDE (stack traces são ótimos professores!) para entender como o Collector interage com o código do seu componente.

Pré-requisitos

A ferramenta ocb requer Go para compilar a distribuição do Collector. Certifique-se de instalar uma versão compatível do Go em sua máquina antes de começar.

Instalar o OpenTelemetry Collector Builder

O binário ocb está disponível como um recurso (asset) para download nas versões do OpenTelemetry Collector com tags cmd/builder. Encontre e baixe o recurso compatível com seu sistema operacional e arquitetura de processador:

• Linux (AMD 64)
• Linux (ARM 64)
• Linux (ppc64le)
• macOS (AMD 64)
• macOS (ARM 64)
• Windows (AMD 64)

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.148.0/ocb_0.148.0_linux_amd64
chmod +x ocb

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.148.0/ocb_0.148.0_linux_arm64
chmod +x ocb

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.148.0/ocb_0.148.0_linux_ppc64le
chmod +x ocb

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.148.0/ocb_0.148.0_darwin_amd64
chmod +x ocb

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.148.0/ocb_0.148.0_darwin_arm64
chmod +x ocb

Invoke-WebRequest -Uri "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.148.0/ocb_0.148.0_windows_amd64.exe" -OutFile "ocb.exe"
Unblock-File -Path "ocb.exe"

Para verificar se o ocb foi instalado corretamente, execute ./ocb help no terminal. A saída do comando help deve ser exibida no console.

Configurar o OpenTelemetry Collector Builder

Configure o ocb com um arquivo de manifesto YAML. O manifesto possui duas seções principais. A primeira seção, dist, contém opções para configurar a geração de código e o processo de compilação. A segunda seção contém os tipos de módulos de nível superior, como extensions, exporters, receivers ou processors. Cada tipo de módulo aceita uma lista de componentes.

A seção dist do manifesto contém tags que são equivalentes às flags de linha de comando do ocb. A tabela a seguir lista as opções para configurar a seção dist.

Todas as tags de dist são opcionais. É possível adicionar valores personalizados para elas, dependendo se pretende disponibilizar sua distribuição personalizada do Collector para outros usuários ou se está usando o ocb para inicializar seu ambiente de desenvolvimento e teste de componentes.

Para configurar o ocb, siga estas etapas:

1. Crie um arquivo de manifesto chamado builder-config.yaml com o seguinte conteúdo:

   dist:
     name: otelcol-dev
     description: Distribuição básica do OTel Collector para desenvolvedores
     output_path: ./otelcol-dev
   

2. Adicione módulos para os componentes que deseja incluir nesta distribuição personalizada do Collector. Consulte a documentação de configuração do ocb para entender os diferentes módulos e como adicionar componentes.

   Para esta distribuição de exemplo, adicione os seguintes componentes:

   • Exporters: OTLP e Debug
   • Receivers: OTLP
   • Processors: Batch

   O arquivo de manifesto builder-config.yaml deve ficar assim:

   dist:
     name: otelcol-dev
     description: Distribuição básica do OTel Collector para desenvolvedores
     output_path: ./otelcol-dev
   
   exporters:
     - gomod:
         go.opentelemetry.io/collector/exporter/debugexporter v0.148.0
     - gomod:
         go.opentelemetry.io/collector/exporter/otlpexporter v0.148.0
   
   processors:
     - gomod:
         go.opentelemetry.io/collector/processor/batchprocessor v0.148.0
   
   receivers:
     - gomod:
         go.opentelemetry.io/collector/receiver/otlpreceiver v0.148.0
   
   providers:
     - gomod:
         go.opentelemetry.io/collector/confmap/provider/envprovider v1.48.0
     - gomod:
         go.opentelemetry.io/collector/confmap/provider/fileprovider v1.48.0
     - gomod:
         go.opentelemetry.io/collector/confmap/provider/httpprovider v1.48.0
     - gomod:
         go.opentelemetry.io/collector/confmap/provider/httpsprovider v1.48.0
     - gomod:
         go.opentelemetry.io/collector/confmap/provider/yamlprovider v1.48.0
   

Gerar o código e compilar sua distribuição do Collector

Com o ocb instalado e configurado, é possível compilar sua distribuição.

No terminal, execute o seguinte comando para iniciar o ocb:

./ocb --config builder-config.yaml

A saída do comando deve ser semelhante a esta:

2025-06-13T14:25:03.037-0500	INFO	internal/command.go:85	OpenTelemetry Collector distribution builder	{"version": "0.148.0", "date": "2025-06-03T15:05:37Z"}
2025-06-13T14:25:03.039-0500	INFO	internal/command.go:108	Using config file	{"path": "builder-config.yaml"}
2025-06-13T14:25:03.040-0500	INFO	builder/config.go:99	Using go	{"go-executable": "/usr/local/go/bin/go"}
2025-06-13T14:25:03.041-0500	INFO	builder/main.go:76	Sources created	{"path": "./otelcol-dev"}
2025-06-13T14:25:03.445-0500	INFO	builder/main.go:108	Getting go modules
2025-06-13T14:25:04.675-0500	INFO	builder/main.go:87	Compiling
2025-06-13T14:25:17.259-0500	INFO	builder/main.go:94	Compiled	{"binary": "./otelcol-dev/otelcol-dev"}

Conforme definido na seção dist do manifesto, agora existe uma pasta chamada otelcol-dev contendo todo o código-fonte e o binário da sua distribuição do Collector.

A estrutura da pasta será semelhante a esta:

.
├── builder-config.yaml
├── ocb
└── otelcol-dev
    ├── components.go
    ├── components_test.go
    ├── go.mod
    ├── go.sum
    ├── main.go
    ├── main_others.go
    ├── main_windows.go
    └── otelcol-dev

É possível utilizar o código gerado para inicializar seus projetos de desenvolvimento de componentes e, em seguida, compilar e distribuir sua própria distribuição do Collector com esses componentes.

Conteinerizar sua distribuição do Collector

Siga estas etapas para gerar o contêiner do seu Collector personalizado.

1. Adicione dois novos arquivos ao projeto:

   • Dockerfile - Definição da imagem de contêiner da sua distribuição do Collector
   • collector-config.yaml - YAML de configuração mínima do Collector para testar sua distribuição

   Após adicionar esses arquivos, a estrutura de arquivos ficará assim:

   .
   ├── builder-config.yaml
   ├── collector-config.yaml
   └── Dockerfile
   

2. Adicione o seguinte conteúdo ao Dockerfile. Esta definição compila sua distribuição do Collector localmente (in-place) e garante que o binário resultante da distribuição do Collector corresponda à arquitetura do contêiner de destino (por exemplo, linux/arm64, linux/amd64):

   FROM alpine:3.19 AS certs
   RUN apk --update add ca-certificates
   
   FROM golang:1.25.0 AS build-stage
   WORKDIR /build
   
   COPY ./builder-config.yaml builder-config.yaml
   
   RUN --mount=type=cache,target=/root/.cache/go-build GO111MODULE=on go install go.opentelemetry.io/collector/cmd/builder@v0.148.0
   RUN --mount=type=cache,target=/root/.cache/go-build builder --config builder-config.yaml
   
   FROM gcr.io/distroless/base:latest
   
   ARG USER_UID=10001
   USER ${USER_UID}
   
   COPY ./collector-config.yaml /otelcol/collector-config.yaml
   COPY --from=certs /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
   COPY --chmod=755 --from=build-stage /build/otelcol-dev /otelcol
   
   ENTRYPOINT ["/otelcol/otelcol-dev"]
   CMD ["--config", "/otelcol/collector-config.yaml"]
   
   EXPOSE 4317 4318 12001
   

1. Adicione a seguinte definição ao seu arquivo collector-config.yaml:

   receivers:
     otlp:
       protocols:
         grpc:
           endpoint: 0.0.0.0:4317
         http:
           endpoint: 0.0.0.0:4318
   
   exporters:
     debug:
       verbosity: detailed
   
   service:
     pipelines:
       traces:
         receivers: [otlp]
         exporters: [debug]
       metrics:
         receivers: [otlp]
         exporters: [debug]
       logs:
         receivers: [otlp]
         exporters: [debug]
   

2. Use os seguintes comandos para compilar uma imagem Docker multi-arquitetura do ocb usando linux/amd64 e linux/arm64 como as arquiteturas de compilação de destino. Para saber mais, consulte este artigo sobre compilações multi-arquitetura.

   # Habilitar compilações multi-arquitetura no Docker
   docker run --rm --privileged tonistiigi/binfmt --install all
   docker buildx create --name mybuilder --use
   
   # Compilar a imagem Docker como Linux AMD e ARM
   # e carregar o resultado para o "docker images" local
   docker buildx build --load \
     -t <collector_distribution_image_name>:<version> \
     --platform=linux/amd64,linux/arm64 .
   
   # Testar a imagem recém-compilada
   docker run -it --rm -p 4317:4317 -p 4318:4318 \
       --name otelcol <collector_distribution_image_name>:<version>
   

Leituras complementares

• Criar um receiver
• Criar um connector