Documentation issue in: Building a custom collector

[hyang023]

on documentation page https://opentelemetry.io/docs/collector/custom-collector/ in Step 2, the builder-config.yaml manifest file contains a line where dist. otelcol_version: 0.103.1 which conflicts with the 0.103.0 version used throughout the rest of the file this results in errors in the next step (Step 3 - Generating the Code and Building your Collector’s distribution):

$ ./ocb --config builder-config.yaml
2024-06-21T11:40:31.911-0700    INFO    internal/command.go:125 OpenTelemetry Collector Builder {"version": "0.103.1", "date": "2024-06-18T16:22:33Z"}
2024-06-21T11:40:31.912-0700    INFO    internal/command.go:161 Using config file   {"path": "builder-config.yaml"}
2024-06-21T11:40:31.912-0700    INFO    builder/config.go:141   Using go    {"go-executable": "/usr/local/go/bin/go"}
2024-06-21T11:40:31.912-0700    INFO    builder/main.go:77  You're building a distribution with non-aligned version of the builder. Compilation may fail due to API changes. Please upgrade your builder or API {"builder-version": "0.103.0"}
2024-06-21T11:40:31.913-0700    INFO    builder/main.go:100 Sources created {"path": "./otelcol-dev"}
Error: failed to update go.mod: go subcommand failed with args '[mod tidy -compat=1.21]': exit status 1, error message: go: downloading go.opentelemetry.io/collector/confmap/provider/httpprovider v0.103.1
go: downloading go.opentelemetry.io/collector/confmap/converter/expandconverter v0.103.1
go: downloading go.opentelemetry.io/collector/confmap/provider/envprovider v0.103.1
go: downloading go.opentelemetry.io/collector/confmap/provider/fileprovider v0.103.1
go: downloading go.opentelemetry.io/collector/confmap/provider/httpsprovider v0.103.1
go: downloading go.opentelemetry.io/collector/confmap/provider/yamlprovider v0.103.1
go: downloading go.opentelemetry.io/collector/otelcol v0.103.1
go: go.opentelemetry.io/collector/confmap/converter/expandconverter@v0.103.1: reading go.opentelemetry.io/collector/confmap/converter/expandconverter/go.mod at revision confmap/converter/expandconverter/v0.103.1: unknown revision confmap/converter/expandconverter/v0.103.1

workaround used: changing the line to dist. otelcol_version: 0.103.0 results in a successful build:

$ ./ocb --config builder-config.yaml
2024-06-21T11:43:12.208-0700    INFO    internal/command.go:125 OpenTelemetry Collector Builder {"version": "0.103.1", "date": "2024-06-18T16:22:33Z"}
2024-06-21T11:43:12.208-0700    INFO    internal/command.go:161 Using config file   {"path": "builder-config.yaml"}
2024-06-21T11:43:12.208-0700    INFO    builder/config.go:141   Using go    {"go-executable": "/usr/local/go/bin/go"}
2024-06-21T11:43:12.210-0700    INFO    builder/main.go:100 Sources created {"path": "./otelcol-dev"}
2024-06-21T11:43:14.569-0700    INFO    builder/main.go:191 Getting go modules
2024-06-21T11:43:15.791-0700    INFO    builder/main.go:111 Compiling
2024-06-21T11:43:32.106-0700    INFO    builder/main.go:130 Compiled    {"binary": "./otelcol-dev/otelcol-dev"}

[tiffany76]

Thanks for reporting your issue, @hyang023.

@open-telemetry/collector-approvers, could you confirm that the workaround is the right fix?

[mx-psi]

Yes, otelcol_version should be set to 0.103.0. We had a bugfix release of the builder, but we did not release a v0.103.1 release of the rest of core modules. We likely need to update the docs automation to account for this edge case.

[svrnm]

Yes, otelcol_version should be set to 0.103.0. We had a bugfix release of the builder, but we did not release a v0.103.1 release of the rest of core modules. We likely need to update the docs automation to account for this edge case.

@chalin please take a look, this seems to be something where we need to update some scripts

[tiffany76]

Since this fix is likely related to infrastructure, I removed the good first issue label.

[chalin]

@svrnm - took a quick look. I don't think that we want any automation to handle this edge case, but rather simply (temporarily) override the version in the file in question. How does that sound @mx-psi et al? Of course we'll need to remember to remover the override if we vote for such a solution.

[svrnm]

if we do a temporary fix we need a way to remind us to revert it eventually, but agreed if this is an edge case that will not happen regularly we should not automate it away

[mx-psi]

Agreed that this is a pretty rare case. If the situation changes the Collector SIG and we somehow decouple builder and Collector releases we can let you know