Tracker: Improve Operator documentation and provide usecase examples

[frzifus]

Component(s)

No response

Describe the issue you're reporting

As discussed in the last OpenTelemetry-SIG call, we would like to prepare our docs. And outline the areas that need some improvement.

Our readme has become bigger and bigger durng the last year. It contains a basic explanation how to use the v1alphav1 CR, the instrumentation CRD, details about supported auto-instrumentation libaries, details about the target allocator and so on.

We may want to move this into a more structured docs section and sorted by usecases. Providing good examples and reference configuration snippeds from the e2e tests to keep them up-to-date.

Afterwards our readme should only provide an index.

Items

• TBD

---

As discussed during the meeting, we may want to apply for the 2024 Google seasons of docs:

• Announcing Blog post
• APPLICATION DEADLINE: April 2, 2024 at 18:00 UTC
• Rules
• Responsibilities

Participants/Volunteer:

• @jaronoff97 Maintainer
• @max-cx Technical Writer
• (drop a message in this thread)

TODO

https://developers.google.com/season-of-docs/docs/admin-guide#exploration_phase

[zeitlinger]

What I found:

1. https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-operator#opentelemetry-operator-helm-chart does not explain that you need to install an Instrumentation
2. The collector spec in https://opentelemetry.io/docs/kubernetes/operator/#getting-started has a trace pipeline, but not metrics or logs - this causes surprising errors (also https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-operator#deployment-mode, https://github.com/open-telemetry/opentelemetry-operator?tab=readme-ov-file#getting-started)
3. comment is wrong - javaagent is now 2.3.0

[justsomecorporateuser]

Wanted to share some thoughts i'm currently having. Having installed operator in one test environment as proof-of-concept, now wondering how to structure the real deal in 10 other clusters. Target would be to provide developers as easy way as possible to get metrics & tracing working but then also make it possible for them to either instrument self or be able to adjust parameters without ops involvement

Questions in my mind are these:

• multiple Collectors with different combinations of trace/metric/logging enabled?
• multiple Instrumentations with different setups? Or one default + ability for devs to specify own ones if defaults do not fit
• Cases where Auto-instrumentation is not enough and app would need for example custom Spans added - who is in control of Opentelemetry agent libraries? Is it Auto-instrumented agent with its libraries or the ones which developers added to the app which are used? Can i break those implementations by updating Operators instrumentation images to fresh version? E.g what are the implications if any when taking the route from auto-instrumentation to code-based approach
• i guess OpAMP is a bit outside operator scope, but that does change the way how to manage the setup, right?

Would be nice to have something about these in the documentation