otel-collector-builder

Name: otel-collector-builder
Author: ollygarden

69stars6forks

How to install otel-collector-builder?

ollygarden/opentelemetry-agent-skills/otel-collector-builder

$npx -y skills add ollygarden/opentelemetry-agent-skills --skill otel-collector-builder

Installs into the current project.

Summary

Build custom OpenTelemetry Collector distributions with OCB (OpenTelemetry Collector Builder). Use when authoring or debugging a builder manifest (builder.yaml), choosing component and provider versions, building a collector that bundles a custom or out-of-distribution component,

Files · 1

View on GitHub

SKILL.md

1	# OpenTelemetry Collector Builder (OCB)
2
3	OCB generates and compiles a custom Collector binary from a YAML manifest that lists exactly the components to include. Source of truth: [cmd/builder](https://github.com/open-telemetry/opentelemetry-collector/tree/main/cmd/builder) in opentelemetry-collector.
4
5	Use OCB when the stock `otelcol`/`otelcol-contrib` distributions don't fit: you need a component that ships in no distribution, a private/local component, or a slimmer binary with only the components you run.
6
7	This skill covers building the distribution. For configuring individual components, see `otel-collector`; for writing a new component, see the component-authoring guidance; for generating test traffic against the built binary, see `otel-telemetrygen`.
8
9	## Workflow
10
11	1. Install OCB at the version matching your target Collector version (see [Install](#install)).
12	2. Write the manifest — `dist:` block plus component lists. Start from the [minimal manifest](#minimal-manifest); full key reference in [references/manifest.md](references/manifest.md).
13	3. Align versions. All core components share one `v0.x.0` version, contrib components use the same `v0.x.0`, and confmap providers use the paired stable `v1.y.0`. Getting this wrong is the #1 build failure — see [Version alignment](#version-alignment).
14	4. Build with `ocb --config=builder.yaml` (binary is named `builder` when installed via `go install`). CI, Docker, multi-arch, and local-component workflows are in [references/workflows.md](references/workflows.md).
15	5. Verify: run `./dist/<name> validate --config=<collector-config>.yaml`, then start it and send test data (`otel-telemetrygen` skill). If the build fails, see [references/troubleshooting.md](references/troubleshooting.md).
16
17	## Install
18
19	Pick the OCB version equal to the Collector core version you're targeting.
20
21	```bash
22	# Release binary (named ocb): https://github.com/open-telemetry/opentelemetry-collector-releases/releases?q=cmd/builder
23	# Go install (binary is named `builder`, not `ocb`):
24	go install go.opentelemetry.io/collector/cmd/builder@v0.156.0
25	```
26
27	`ocb init` (experimental) scaffolds a new distribution repo — manifest, Makefile, sample config, README — in `--path` (default `.`).
28
29	## Minimal manifest
30
31	```yaml
32	# builder.yaml
33	dist:
34	name: otelcol-custom
35	description: Custom OpenTelemetry Collector distribution
36	output_path: ./dist
37	version: 1.0.0
38
39	receivers:
40	- gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.156.0
41
42	processors:
43	- gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.156.0
44
45	exporters:
46	- gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.156.0
47	- gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.156.0
48
49	providers:
50	- gomod: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.62.0
51	- gomod: go.opentelemetry.io/collector/confmap/provider/envprovider v1.62.0
52	```
53
54	`providers:` semantics. Omitting the key entirely keeps OCB's built-in default set (env, file, http, https, yaml at the paired stable version). But setting `providers:` at all replaces that set. The generated Collector defaults `conf_resolver.default_uri_scheme` to `env`, so an explicit list without `envprovider` fails configuration validation unless you set another included provider as the default. Either omit the key, or include `envprovider` plus every scheme the collector's config will use.
55
56	Contrib components use the same list syntax:
57
58	```yaml
59	processors:
60	- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/tailsamplingprocessor v0.156.0
61	```
62
63	## Version alignment
64
65	Two version streams exist and must be paired:
66
67	\| Stream \| Modules \| Example \|
68	\|--------\|---------\|---------\|
69	\| `v0.x.0` \| OCB itself, all core components (`go.opentelemetry.io/collector/...`), all contrib components \| `v0.156.0` \|
70	\| `v1.y.0` (stable) \| confmap providers (`confmap/provider/...`), other 1.x modules (pdata, etc.) \| `v1.62.0` \|
71
72	Rules:
73
74	- Use the same `v0.x.0` for every core and contrib component, matched to the OCB version.
75	- The paired provider version for a given release is authoritative in that release's embedded default manifest: `https://github.com/open-telemetry/opentelemetry-collector/blob/cmd/builder/v0.x.0/cmd/builder/internal/config/default.yaml` — check it rather than guessing (for `v0.156.0` it is `v1.62.0`).
76	- Versions require the `v` prefix (`v0.156.0

ollygardenPublisher · 16 listings

Preview

ollygarden/opentelemetry-agent-skills

# OpenTelemetry Collector Builder (OCB)

OCB generates and compiles a custom Collector binary from a YAML manifest that lists exactly the components to include. Source of truth: [cmd/builder](https://g

Use OCB when the stock `otelcol`/`otelcol-contrib` distributions don't fit: you need a component that ships in no distribution, a private/local component, or a

This skill covers building the distribution. For configuring individual components, see `otel-collector`; for writing a new component, see the component-authori

Repoollygarden/opentelemetry-agent-skills

LicenseApache-2.0

TypeSkills

CategoryInfrastructure

UpdatedJul 2026

Repo stars69

First seenJul 22, 2026

People who liked this also viewed

6 picks

Type

otel-collector-builder

69stars6forks

View on GitHub

How to install otel-collector-builder?

ollygarden/opentelemetry-agent-skills/otel-collector-builder

$npx -y skills add ollygarden/opentelemetry-agent-skills --skill otel-collector-builder

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# OpenTelemetry Collector Builder (OCB)
2
3	OCB generates and compiles a custom Collector binary from a YAML manifest that lists exactly the components to include. Source of truth: [cmd/builder](https://github.com/open-telemetry/opentelemetry-collector/tree/main/cmd/builder) in opentelemetry-collector.
4
5	Use OCB when the stock `otelcol`/`otelcol-contrib` distributions don't fit: you need a component that ships in no distribution, a private/local component, or a slimmer binary with only the components you run.
6
7	This skill covers building the distribution. For configuring individual components, see `otel-collector`; for writing a new component, see the component-authoring guidance; for generating test traffic against the built binary, see `otel-telemetrygen`.
8
9	## Workflow
10
11	1. Install OCB at the version matching your target Collector version (see [Install](#install)).
12	2. Write the manifest — `dist:` block plus component lists. Start from the [minimal manifest](#minimal-manifest); full key reference in [references/manifest.md](references/manifest.md).
13	3. Align versions. All core components share one `v0.x.0` version, contrib components use the same `v0.x.0`, and confmap providers use the paired stable `v1.y.0`. Getting this wrong is the #1 build failure — see [Version alignment](#version-alignment).
14	4. Build with `ocb --config=builder.yaml` (binary is named `builder` when installed via `go install`). CI, Docker, multi-arch, and local-component workflows are in [references/workflows.md](references/workflows.md).
15	5. Verify: run `./dist/<name> validate --config=<collector-config>.yaml`, then start it and send test data (`otel-telemetrygen` skill). If the build fails, see [references/troubleshooting.md](references/troubleshooting.md).
16
17	## Install
18
19	Pick the OCB version equal to the Collector core version you're targeting.
20
21	```bash
22	# Release binary (named ocb): https://github.com/open-telemetry/opentelemetry-collector-releases/releases?q=cmd/builder
23	# Go install (binary is named `builder`, not `ocb`):
24	go install go.opentelemetry.io/collector/cmd/builder@v0.156.0
25	```
26
27	`ocb init` (experimental) scaffolds a new distribution repo — manifest, Makefile, sample config, README — in `--path` (default `.`).
28
29	## Minimal manifest
30
31	```yaml
32	# builder.yaml
33	dist:
34	name: otelcol-custom
35	description: Custom OpenTelemetry Collector distribution
36	output_path: ./dist
37	version: 1.0.0
38
39	receivers:
40	- gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.156.0
41
42	processors:
43	- gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.156.0
44
45	exporters:
46	- gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.156.0
47	- gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.156.0
48
49	providers:
50	- gomod: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.62.0
51	- gomod: go.opentelemetry.io/collector/confmap/provider/envprovider v1.62.0
52	```
53
54	`providers:` semantics. Omitting the key entirely keeps OCB's built-in default set (env, file, http, https, yaml at the paired stable version). But setting `providers:` at all replaces that set. The generated Collector defaults `conf_resolver.default_uri_scheme` to `env`, so an explicit list without `envprovider` fails configuration validation unless you set another included provider as the default. Either omit the key, or include `envprovider` plus every scheme the collector's config will use.
55
56	Contrib components use the same list syntax:
57
58	```yaml
59	processors:
60	- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/tailsamplingprocessor v0.156.0
61	```
62
63	## Version alignment
64
65	Two version streams exist and must be paired:
66
67	\| Stream \| Modules \| Example \|
68	\|--------\|---------\|---------\|
69	\| `v0.x.0` \| OCB itself, all core components (`go.opentelemetry.io/collector/...`), all contrib components \| `v0.156.0` \|
70	\| `v1.y.0` (stable) \| confmap providers (`confmap/provider/...`), other 1.x modules (pdata, etc.) \| `v1.62.0` \|
71
72	Rules:
73
74	- Use the same `v0.x.0` for every core and contrib component, matched to the OCB version.
75	- The paired provider version for a given release is authoritative in that release's embedded default manifest: `https://github.com/open-telemetry/opentelemetry-collector/blob/cmd/builder/v0.x.0/cmd/builder/internal/config/default.yaml` — check it rather than guessing (for `v0.156.0` it is `v1.62.0`).
76	- Versions require the `v` prefix (`v0.156.0

ollygardenPublisher · 16 listings

Preview

ollygarden/opentelemetry-agent-skills

# OpenTelemetry Collector Builder (OCB)

OCB generates and compiles a custom Collector binary from a YAML manifest that lists exactly the components to include. Source of truth: [cmd/builder](https://g

Use OCB when the stock `otelcol`/`otelcol-contrib` distributions don't fit: you need a component that ships in no distribution, a private/local component, or a

This skill covers building the distribution. For configuring individual components, see `otel-collector`; for writing a new component, see the component-authori

Repoollygarden/opentelemetry-agent-skills

LicenseApache-2.0

TypeSkills

CategoryInfrastructure

UpdatedJul 2026

Repo stars69

First seenJul 22, 2026

People who liked this also viewed

6 picks

Type