Collector Getting Started Rewrite

[svrnm]

Copying this from #1368 (comment):

• 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.

cc: @jpkrohling

[theletterf]

I'd like to take this.

[cartermp]

All yours!

[theletterf]

I'm finally starting this and I've some general questions:

• Some of the snippets, especially the ones for Linux, WIndows, etc. link to otelcol packages. Any reason why we shouldn't link to the contrib packages, which carry all the components one might need?
• The current doc starts with the demo, then goes to Docker, Kubernetes, and finally the operating systems's binaries. Is that the progression we want? Wouldn't it make more sense to start from the binaries then go to Docker and then make the jump to Kubernetes and the demo in the end (or link to a subpage)?

[jpkrohling]

If we can "get started" with an OTLP receiver and exporter, plus batching, we should be able to do it with the core distribution. Using contrib would be better when showcasing other component,s like Prometheus receivers/exporters, but we do not recommend using contrib in production, so it would require a disclaimer on that page.

I would prefer to start small, OTLP in/out + batching, and evolve from there.

[svrnm]

Hey @theletterf, thanks for picking this up, here are my few thoughts on this topic:

The current Getting Started guide is just a collection of installation mechanisms, so I would rename that page to "Installation" or "Setup" or whatever and keep it separate from the Getting Started

Pick a way of installing the collector that is easy for a getting started (Docker + downloading the binary in a tabbing), you can be prescriptive here and point to the Installation page for other options.

The guide itself should be similar to the language guides something to get people started and give them something to play around with. Could even take some sections from @frzifus' work for our tutorial at Kubecon earier this year: https://github.com/pavolloffay/kubecon-eu-2023-opentelemetry-kubernetes-tutorial/blob/main/01-collector-introduction.md

E.g.:

• Download the (core) collector
• Create a basic config (otlp in, write everything to the console)
• Send some telemetry to that collector (use telemetrygen or whatever makes sense, you can also point out that some of the language getting started can be followed and used for that?)
• Update the config to contain batching
• Update the config with batching
• Update the config to point to an OTLP endpoint (Jaeger, Prometheus with the receiver,)
• Mention that you can have more than that and pick some of the receivers included in core: https://github.com/open-telemetry/opentelemetry-collector-releases/blob/main/distributions/otelcol/manifest.yaml (apply some processors, add some receivers, etc)
• End with a "What's next" section that points out that you can use OCB to build your own thing, that you can use it with k8s & operator, etc. pp.

(That's how I think about it, so while you create that thing don't hesitate to strip/change any of that. I think we are also fine if we only start with 50% of that and grow from there)

[theletterf]

Online!