Oh boy that hits home. Been deep in the OTEL world the last months and the official docs are very, very undercooked.

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.

One of my OPs guys tried to gently steer me toward Prometheus after one of the others said use OpenTelemetry.

Fuck OTEL. That is S-tier designed by committee bullshit. The DevEx would make the Marquis de Sade blush. The former person had to do wireshark captures for us to figure out where my stats were disappearing.

Twice.

Fuck OTEL. Fuck it right in the ear. Fuck all of the collaborators too (and I mean that in the war crimes sense of collaborators)

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

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.

Several things I needed were in completely separate documents not linked together.

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. :-)

I feel like it is endemic to anything OPS / DevOPS. Lot of uselessly verbose "documentation" but no list of whatever you really need.

All in the name of selling products which abstract those parts, consulting or courses.

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.

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 :)

https://github.com/joaopgrassi/otel-recipes