Skip to content

Doc/go tool for builder #12990

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Doc/go tool for builder #12990

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8ba53dc
Update TLDR section
May 7, 2025
29399ea
Add builder as tool in go.mod
May 7, 2025
012665a
Update README with go get --tool
May 8, 2025
387a016
Update README (minor fixes)
May 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 32 additions & 11 deletions cmd/builder/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,30 +5,30 @@ This program generates a custom OpenTelemetry Collector binary based on a given
## TL;DR

```console
$ go install go.opentelemetry.io/collector/cmd/builder@v0.109.0
$ go get --tool go.opentelemetry.io/collector/cmd/builder@v0.125.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.109.0
- gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.109.0
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/exporter/alibabacloudlogserviceexporter v0.125.0
- gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.125.0

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

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

providers:
- gomod: go.opentelemetry.io/collector/confmap/provider/envprovider v1.15.0
- gomod: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.15.0
- gomod: go.opentelemetry.io/collector/confmap/provider/httpprovider v0.109.0
- gomod: go.opentelemetry.io/collector/confmap/provider/httpsprovider v0.109.0
- gomod: go.opentelemetry.io/collector/confmap/provider/yamlprovider v0.109.0
- gomod: go.opentelemetry.io/collector/confmap/provider/httpprovider v0.125.0
- gomod: go.opentelemetry.io/collector/confmap/provider/httpsprovider v0.125.0
- gomod: go.opentelemetry.io/collector/confmap/provider/yamlprovider v0.125.0
EOF
$ builder --config=otelcol-builder.yaml
$ go tool builder --config=otelcol-builder.yaml
$ cat > /tmp/otelcol.yaml <<EOF
receivers:
otlp:
Expand Down Expand Up @@ -61,6 +61,7 @@ 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)
4. Through `go get --tool`

### Official release Docker image

Expand Down Expand Up @@ -88,6 +89,8 @@ Additional arguments may be passed to ocb on the command line as specified below

This is the recommended installation method for the binary. Download the binary for your respective platform from the ["Releases"](https://github.com/open-telemetry/opentelemetry-collector-releases/releases?q=cmd/builder) page.

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

### `go install`

You need to have a `go` compiler in your PATH. Run the following command to install the latest version:
Expand All @@ -96,7 +99,7 @@ You need to have a `go` compiler in your PATH. Run the following command to inst
go install go.opentelemetry.io/collector/cmd/builder@latest
```

If installing through this method the binary will be called `builder`.
If installed 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](../../README.md#compatibility).

Expand All @@ -110,7 +113,25 @@ To build a default collector configuration, you can use [this](../otelcorecol/bu
ocb --config=builder-config.yaml
```

Use `ocb --help` to learn about which flags are available.
### `go get --tool` (go version >= 1.24)

You need to have a `go` compiler in your PATH, as well as a Go project containing a `go.mod` file.

Run the following command to register the `builder` CLI as a go tool.

```console
go get --tool go.opentelemetry.io/collector/cmd/builder
```

If Installed through this method, the binary can be called with `go tool builder`. Note that it will only be accessible from within your Go project.

The upside of using `go get --tool` over the other aforementioned method is that the go toolchain manages the binary like any other dependency.
Comment on lines +126 to +128
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two more suggestions, to make clear what "managed like any other dependency" means.

Suggested change
If Installed through this method, the binary can be called with `go tool builder`. Note that it will only be accessible from within your Go project.
The upside of using `go get --tool` over the other aforementioned method is that the go toolchain manages the binary like any other dependency.
If installed through this method, the binary can be called with `go tool builder`. Note that it will only be accessible from within your Go project.
The upside of using `go get --tool` over the other aforementioned method is that the go toolchain manages the binary like any other dependency: a `tool` directive will be added to your `go.mod` file.


This has a couple upsides:

- You can pin the version of the builder used to build your distribution, which also pins the version of the core Collector libraries used as part of it. This ensures compatibility with imports of OTel libraries within your component code.
- Different go projects using different versions will use different `builder` managed automatically instead of forcing the user to download multiple versions of the binary.


## Debug

Expand Down
2 changes: 2 additions & 0 deletions cmd/builder/go.mod
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,3 +42,5 @@ retract (
v0.57.1 // Release failed, use v0.57.2
v0.57.0 // Release failed, use v0.57.2
)

tool go.opentelemetry.io/collector/cmd/builder
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does it makes sense to add OCB as a tool in its own mod file? My assumption is that this would only be useful if we use the builder to build the builder.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i don't have enough knowledge about OTEL to answer that question.

It's my first time using the OCB, i was fighting for a couple hours with binary versions and when i though about go tool and noticed how good the experience was i came here to open an issue and a PR.

This should be discussed separately i think

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BTW about your other comment about running the go get --tool,
i've cleaned up all my deps and my cache just in case and it's working just fine.

i'm using:

  • go version go1.24.0 darwin/arm64
  • go version go1.24.2 linux/amd64

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. I tried creating a brand new Go project and go get --tools works, whereas it doesn't work in my existing project. It seems like the existing dependencies can interfere with it; maybe we should call this out?

Copy link
Contributor

@jade-guiton-dd jade-guiton-dd May 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regarding this line, I think we should remove it from the PR. The tool directive only makes sense in the module where we plan to use the tool.