Unclear control flow

[exFalso]

Hi, can you add some documentation on how Spans, Contexts and Tracers interact in an async setting? It's completely opaque, and I've been trying to make extremely simple use cases work with little to no success. Sometimes tracer.start-ing the span is enough, sometimes it just creates a tiny span of a couple of microseconds. Sometimes the Context is set correctly in the thread local, sometimes it isn't. Sometimes I need to pass the span with context.with_span() sometimes I don't. It's all over the place.
It feels like I need to actually understand the internal control flow of the library just to be able to propagate the trace context around the infrastructure, very unintuitive. Although it's still better than rust tracing, at least the library code is readable.

Anyway, so the ask is: Please add documentation on the control and data flow of how these values are propagated, and under what situation we need to use Contexts vs Spans in an async setting. Thank you. Yes I looked at examples/ and they're not sufficient.

[cijothomas]

Agree this is something to be improved in docs and/or examples!
https://github.com/open-telemetry/opentelemetry-rust/tree/main/examples/tracing-http-propagator was updated recently, so some of the questions maybe already answered.