[bug] The process of "Building a Trace Receiver" is broken

[brightzheng100]

What happened? Describe the problem that occurred.

Was trying to follow the "Building a Trace Receiver" to walk through the process of building a trace receiver, but I was stuck at step of "Adding the receiver factory to the Collector’s initialization".

It's obvious that, before we run below command, after importing the github.com/rquedas/otel4devs/collector/receiver/trace-receiver/tailtracer module, a new compilation should be required:

$ ./otelcol-dev --config config.yaml

Otherwise below exception is expected:

$ ./otelcol-dev --config config.yaml
Error: failed to get config: cannot unmarshal the configuration: 1 error(s) decoding:

* error decoding 'receivers': unknown type: "tailtracer" for id: "tailtracer" (valid values: [otlp])
2023/11/04 21:56:45 collector server run finished with error: failed to get config: cannot unmarshal the configuration: 1 error(s) decoding:

* error decoding 'receivers': unknown type: "tailtracer" for id: "tailtracer" (valid values: [otlp])

However, there is a compilation issue if we simply issue the go build command:

$ go build
components.go:16:2: no required module provides package github.com/rquedas/otel4devs/collector/receiver/trace-receiver/tailtracer; to add it:
	go get github.com/rquedas/otel4devs/collector/receiver/trace-receiver/tailtracer

It won't help if we follow the instructions to go get the required module:

$ go get github.com/rquedas/otel4devs/collector/receiver/trace-receiver/tailtracer
go: github.com/rquedas/otel4devs/collector/receiver/trace-receiver/tailtracer imports
	go.opentelemetry.io/collector/config: cannot find module providing package go.opentelemetry.io/collector/config

What did you expect would happen? Describe the expected result/output.

No doubt, such a tutorial is great and very helpful.

But if it's version specific, please highlight which version(s) are tested, and version pinning might be a good practice to avoid confusion.
And it should be reviewed regularly to make it work for the latest release.

What is the name + path of the page where you encountered the issue? The
relative path and page title where you found a problem.

The Building a Trace Receiver

What browser, OS, and platform were you using when you encountered the
problem? Include the browser version if you know it as well.

MacBook Pro with M1 chip.

Additional context: anything else you can think about that would be helpful.

$ go version
go version go1.21.3 darwin/arm64

[brightzheng100]

After digging into the code and playing with Golang's module design, I realized that there are two issues:

1. The doc misses some necessary steps for how to re-compile the otelcol-dev binary every time after changes in the Golang code.
2. We need to make sure that the code is decoupled from that personal GitHub repo, by using go.mod's replace directive or even Go Workspace, as the code snippet in the doc is valid but the code in that repo is outdated.

I can send a PR to fix above issues that I mentioned if that makes sense.

Meanwhile, I'd suggest to create a new opentelemetry-tutorials repo to host the code with a better repo structure, so that we can host all the code for tutorials mentioned in the official docs.

[cartermp]

PR appreciated!

[brightzheng100]

Okay, let me walk it through again to see where and how to enhance the dev experience with potential practices embedded.

Will prepare and send a PR soon.

[svrnm]

fixed via #3524