Створення власного колектора за допомогою OpenTelemetry Collector Builder

Колектор OpenTelemetry має пʼять офіційних дистрибутивів, як постачаються з певними попередньо налаштованими компонентами. Якщо ви потребуєте більшої гнучкості, ви можете скористатись OpenTelemetry Collector Builder (або ocb) для створення двійкового коду вашого власного дистрибутиву, який міститиме власні компоненти, компоненти проєкту та інші широкодоступні компоненти.

Наступне керівництва показує з чого потрібно почати, щоб створити власний колектор за допомогою ocb. В цьому прикладі ви створите дистрибутив колектора для підтримки розробки та тестування власних компонентів. Ви зможете запускати та відлагоджувати компоненти вашого колектора безпосередньо у вашому оточенні розробки, яке ви використовуєте для мови Go. Використовуйте всі наявні у вашому IDE можливості для відлагодження (трасування стеків є чудовим вчителем!) щоб зрозуміти як колектор взаємодіє з компонентами вашого коду.

Передумови

ocb вимагає наявності Go для збирання дистрибутиву колектора. Переконайтесь що у вас встановлено сумісну версію Go перед тим як розпочати.

Встановлення OpenTelemetry Collector Builder

Бінарний файл ocb доступний для завантаження з випусків OpenTelemetry Collector з теґами cmd/builder. Відшукайте та завантажте потрібний для вашої операційної системи та архітектури процесора елемент:

• 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.146.1/ocb_0.146.1_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.146.1/ocb_0.146.1_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.146.1/ocb_0.146.1_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.146.1/ocb_0.146.1_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.146.1/ocb_0.146.1_darwin_arm64
chmod +x ocb

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

Щоб переконатися, що ocb встановлено коректно, перейдіть до вашого термінала та введіть ./ocb help. Ви повинні побачити вивід команди help у вашій консолі.

Налаштуйте OpenTelemetry Collector Builder

Налаштуйте ocb за допомогою YAML-файлу маніфесту. Маніфест містить два основних розділи. Перший — dist, містить параметри для налаштування генерування коду та процесів компіляції. Другий розділ містить типи модулів верхнього рівня, такі як: extensions, exporters, receivers та processors. Кожен тип модуля приймає перелік компонентів. Розділ маніфесту dist містить теґи, які є еквівалентами прапорців flags командного рядка ocb. В наступній таблиці містяться параметри для налаштування розділу dist.

Всі теґи dist є опціональними. Ви можете додавати власні значення залежно від того чи бажаєте поділитись власним колектором з іншими, чи ви будете використовувати ocb для початкового розгортання ваших компонентів та тестування оточення.

Для налаштування ocb, виконайте наступні кроки:

1. Створіть файл маніфесту з назвою builder-config.yaml з наступним вмістом:

   dist:
     name: otelcol-dev
     description: Basic OTel Collector distribution for Developers
     output_path: ./otelcol-dev
   

2. Додайте модулі для компонентів, які ви хочете включити до власного дистрибутиву колектора. Дивіться документацію з налаштування ocb щоб зрозуміти як працюють різні модулі та як додавати компоненти.

   Додамо наступні компоненти до нашого дистрибутиву колектора:

   • Експортери: OTLP та Debug
   • Приймачі: OTLP
   • Процесори: Batch

   Файл маніфесту builder-config.yaml має виглядатиме так:

   dist:
     name: otelcol-dev
     description: Basic OTel Collector distribution for Developers
     output_path: ./otelcol-dev
   
   exporters:
     - gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.146.1
     - gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.146.1
   
   processors:
     - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.146.1
   
   receivers:
     - gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.146.1
   
   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
   

Згенеруйте код та створіть свій дистрибутив колектора

Зі встановленим та налаштованим ocb ви тепер готові створити свій дистрибутив.

./ocb --config builder-config.yaml

Вивід виглядатиме схожим на це :

2025-06-13T14:25:03.037-0500	INFO	internal/command.go:85	OpenTelemetry Collector distribution builder	{"version": "0.146.1", "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"}

Як визначено в розділі dist вашого маніфесту, тепер у вас є тека з назвою otelcol-dev, що містить весь вихідний код та бінарний файл для вашого дистрибутиву Колектора.

Структура теки виглядає так:

.
├── 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

Ви можете використовувати згенерований код для створення проєктів розробки компонентів та створювати і розповсюджувати власний дистрибутив колектора з вашими компонентами.

Контейнеризуйте дистрибутив вашого колектора

Виконайте наступні кроки для контейнеризації вашого колектора:

1. Додайте два нових фали до вашого проєкту:

   • Dockerfile — визначення образу контейнера вашого дистрибутиву Collector
   • collector-config.yaml — Мінімалістична конфігурація колектора YAML для тестування нашого дистрибутиву

   Після додавання цих файлів ваша файлова структура матиме такий вигляд:

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

2. Додайте наступне до вашого Dockerfile. Це визначення збирає ваш дистрибутив Collector на місці, гарантуючи, що отриманий дистрибутив Collector відповідає цільовій архітектурі контейнера (наприклад, 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.146.1
   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
   

3. Додайте наступні визначення до 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]
   

4. Скористайтеся наведеними нижче командами для створення багатоархітектурного Docker-образу ocb з використанням linux/amd64 і linux/arm64 як цільових архітектур збірки. Щоб дізнатися більше, перегляньте цей допис у блозі про багатоархітектурні збірки.

   # Увімкнення багатоархітектурних збірок Docker
   docker run --rm --privileged tonistiigi/binfmt --install all
   docker buildx create --name mybuilder --use
   
   # Зібрка Docker-образу як Linux AMD та ARM,
   # і завантажує результат збірки до "docker images".
   docker buildx build --load \
     -t <collector_distribution_image_name>:<version> \
     --platform=linux/amd64,linux/arm64 .
   
   # Тестування створеного образу
   docker run -it --rm -p 4317:4317 -p 4318:4318 \
       --name otelcol <collector_distribution_image_name>:<version>
   

Для подальшого ознайомлення

• Створення приймача
• Створення конектора