Oh man, I FEEL this comment. That was one absurdly awful set of documentation, because they not just have a lot of confusingly placed repeat content, they also follow the philosophy of only explaining top level initial conceptual primer for everything, and only explaining the actual main use case of the component 3 navigation pages deep.
So a beginner has to jump a BUNCH of pages to get a primer, and an expert has to bookmark the couple actually-useful pages and later give up and just look at github for specific operators/processors when they already know the basic config inside out.
Same experience. Otel is one of the wordiest docs I've ever come across that says very little.
Further, I found a lot of little bugs that are hard to Google, or when Googling finding open issues that are either known and working on, or no response at all.
I ended up just throwing it in the garbage and using direct connectors. I like what Otel is trying to achieve, but it feels extremely opaque and half baked at the moment.
Yes! Otel, is exactly what I was thinking. It’s for people working on it with access to tribal knowledge.
For mortals working to add it to their service it’s not fit for purpose
I know the feeling, so I built something that hopefully addresses some of this: https://otelrecipes.com. Just launched it last week!
It offers sample applications and a website that shows in a step-by-step manner what you have to do to get OpenTelemetry configured in your apps. My goal is to keep the sample apps to the minimum and focused on a single goal: E.g., I want to add tracing to my app; I want to record metrics; I want to correlate logs with traces etc.
I have lots of ideas and things in the backlog, such as collector recipes.
It's all OSS as well, so anyone can contribute with more samples :)
The best OTel docs I've seen have been from observability vendors. The CNCF needs some volunteer technical writers or something. I think a lot of those docs suffer from being written by people who know the spec inside and out.
Have you given the Getting Started docs pages a go? Indeed it's mostly still reference/conceptual content, and not oriented towards specific workflows yet. We've been wanting to get that kind of content written for quite some time, but the reality is we're a small group (often volunteering our time) and there's still an immense amount of reference and conceptual gaps that need addressing.
When I started using Honeycomb, I had such a wonderful integration experience with their Beeline SDKs.
Then they transitioned to OpenTelemetry – for very good, justifiable, "good community member" reasons – and yikes, everything got so much more complicated. We ended up writing our own moral equivalent to the Beeline SDK. (And Honeycomb have followed up since with their own wrappers.)
There's so much I love about Open Source, but piles and piles of wildly generic, unopinionated code... ooft. :-)
So a beginner has to jump a BUNCH of pages to get a primer, and an expert has to bookmark the couple actually-useful pages and later give up and just look at github for specific operators/processors when they already know the basic config inside out.