Collector: revisit Deployment and Distribution pages

[chalin]

PR #1332 introduced a Deployment page, which doesn't really talk about deployment (i.e., "how to deploy") but rather possible runtime configurations. Consider renaming the page and/or consolidating it with ** Distributions**. Maybe the latter can be folded into the Collector landing page.

Thoughts @svrnm @cartermp @austinlparker?

[cartermp]

I think it is fine to keep it as-is for now. These are about deployment models/strategies. I think we can extend the page over time to have specific guides, but for now it is helpful to describe the concepts.

[svrnm]

+1 for "keeping it as-is for now"

+1 for extending. I thought about this a little bit: this could be an incredible helpful page with a deep dive on this topic. Many people do not see all the potential you have with the collector and I also have people internally asking question about the collector, how to deploy it beyond the basics, etc.

A potential structure:

• Calling out once again the flexibility of the collector and linking back to some basic pages (collector concepts, OTLP, ...).
• Maybe some "basics"/"theory" on deployment (collectors can be chained, there can be LBs and other things between you and the collector, using operators etc for rolling them out)
• "0-collector" deployment, go a little bit more into details when you can use no collector, what advantages you have with that model and when you should consider having a collector. It would be the advanced version of what we have discussed a while back on "why otel collector" with @cartermp.
• agent mode collector
• gateway collector
• ...

For the "..." I was thinking about the work @jpkrohling was doing with his talk on deployment models (This is my go to material when people ask me):

• https://www.youtube.com/watch?v=WhRrwSHDBFs
• https://github.com/jpkrohling/opentelemetry-collector-deployment-patterns/)
  (Of course only if @jpkrohling is OK with that, we also can link there from the docs)

[jpkrohling]

Sorry for the silence on this and other related PRs/issues, I've been AFK for a couple of months and have just returned. I'll review what we currently have and provide my feedback here later this week. If I don't, feel free to ping me directly.

[jpkrohling]

I'm just going through the documentation we have related to the collector and I'll assemble my thoughts here. If desired, we can create issues for the individual points. I can also commit to working on (some of?) them in the short term.

• The Deployment modes page needs some rewording: we don't use the term "Gateway" anywhere else and I think it causes more confusion than clarification.
• There's no different binary nor difference in the configuration between the modes, so it may confuse users. We should either clarify that or remove the notion of "deployment modes" altogether. Perhaps the earlier suggestion on expanding the page to have "patterns" instead would be a good replacement.
• The "Getting Started" starts by requiring people to read two other pages. One of them refers them back to the Getting Started page. I would prefer to have the getting started as the first thing users might read, making a brief explanation on what the collector is and how it fits the big picture.
• In the Getting Started, we should guide users in configuring and running the collector, instead of telling them to just run a docker compose and referring them to the repository. We might still use docker compose to start other things, like Prometheus, Jaeger, and the load generator.
• Everything else on the Getting Started page could go to other sub pages. For instance, running the collector on Kubernetes does not belong to the Getting Started.
• The config under the Configuration page, Exporters section, is a bit odd. For instance, the prometheus exporter specifies prometheus:8889 as the endpoint. As it refers to the same host, I would use either localhost or 0.0.0.0. Similarly, external URLs are following different patterns: "jaeger-all-in-one", "some.url", "example.com", "localhost". I would suggest having them all follow a pattern like "jaeger.example.com", "prometheus.example.com", "otlp.example.com", and "zipkin.example.com"
• The configuration page is missing the telemetry attribute for the service
• A link is desirable for "net/http" mentioned in "Proxy support"
• Perhaps the Distributions page should be joined with the "Build a custom collector". It should also say a few words about vendor-specific distributions.
• The "building a custom collector" page needs some love. The main use case isn't to allow people to run a code within their favorite Go IDE, although that's a good side effect. Also, chmod 777 is never a solution. This page also states a specific version as the latest, which is of course outdated by now.
• Building a Custom Authenticator refers to client authenticator interfaces that have been removed and replaced with https://pkg.go.dev/go.opentelemetry.io/collector/config/configauth#ClientAuthenticator .
• Building a Trace Receiver should probably be renamed to "Building a component". I would assume that a "trace receiver" is just an example of the component to be built. Readers can then expand from the example to build other components, like extensions or exporters.
• The config seems to use Jaeger gRPC port, but the Docker command doesn't export this port. It does export the HTTP one though.
• The guide seems to be using the first person, which doesn't seem consistent with the other pages

I'll amend this comment later with more comments, but I think only this last guide is left to be reviewed.

[svrnm]

If desired, we can create issues for the individual points.

👍 -- we should do that, maybe group them by page.

• The Deployment modes page needs some rewording: we don't use the term "Gateway" anywhere else and I think it causes more confusion than clarification.
• There's no different binary nor difference in the configuration between the modes, so it may confuse users. We should either clarify that or remove the notion of "deployment modes" altogether. Perhaps the earlier suggestion on expanding the page to have "patterns" instead would be a good replacement.

I forked the Deployment page out because of the confusion it creates and it also significantly downplays the things you can do with the collector (by chaining them, etc.), so I am all in for redoing it towards a "patterns" page.

• The "Getting Started" starts by requiring people to read two other pages. One of them refers them back to the Getting Started page. I would prefer to have the getting started as the first thing users might read, making a brief explanation on what the collector is and how it fits the big picture.
• In the Getting Started, we should guide users in configuring and running the collector, instead of telling them to just run a docker compose and referring them to the repository. We might still use docker compose to start other things, like Prometheus, Jaeger, and the load generator.
• Everything else on the Getting Started page could go to other sub pages. For instance, running the collector on Kubernetes does not belong to the Getting Started.

That's a good point! If we compare the Getting Started page of the collector with the individual languages, it's a very different experience, it's just about different ways of installing it vs "here's a 30 minutes tutorial on how to get things up and running". @cartermp and I just touched upon that topic with PHP that most of the language guides have or should have a quick "here's how you setup a collector", e.g. python has it: https://opentelemetry.io/docs/instrumentation/python/getting-started/#configure-and-run-a-local-collector

So yes, moving everything out into a "Installation"(?) page and reducing the Getting Started to such a tutorial would be great.

• Perhaps the Distributions page should be joined with the "Build a custom collector". It should also say a few words about vendor-specific distributions.

We have a "Distributions" page in concepts & for the collector, not sure if/how they can be merged or connected.

• The "building a custom collector" page needs some love. The main use case isn't to allow people to run a code within their favorite Go IDE, although that's a good side effect. Also, chmod 777 is never a solution. This page also states a specific version as the latest, which is of course outdated by now.

cc: @rquedas

• Building a Custom Authenticator refers to client authenticator interfaces that have been removed and replaced with https://pkg.go.dev/go.opentelemetry.io/collector/config/configauth#ClientAuthenticator .

cc: @pavankrish123

• Building a Trace Receiver should probably be renamed to "Building a component". I would assume that a "trace receiver" is just an example of the component to be built. Readers can then expand from the example to build other components, like extensions or exporters.
• The config seems to use Jaeger gRPC port, but the Docker command doesn't export this port. It does export the HTTP one though.
• The guide seems to be using the first person, which doesn't seem consistent with the other pages

cc: @rquedas

[svrnm]

@jpkrohling I think all those todos are great, I bubbled them up to be their own issues so we can close this one and have them visibile.