Docs changes to split out automatic instrumentation, instrumentation packages, and manual instrumentation

[cartermp]

Hello! I'm working on improving docs for all the different language SDKs. In most cases, this means simply adding content, but in some it could imply a little restructure.

The first thing I'm tackling is making sure that automatic instrumentation (if present) and instrumentation libraries (if present) are documented, with an example, easy to find, and distinct from manual instrumentation.

My impression of the docs so far is that most of the content for this is basically written, and examples are good as well. But their organization makes it a little difficult to find. For example, I had two coworkers who struggled to find how to use the autoinstrumentation agent until I pointed them towards the bottom of the docs page.

What I'd like to propose is that "Getting Started" is broken up into 5 sections, in this order:

• Getting Started
  • Hello world: emit a trace to your console
  • Configure exporters to emit spans elsewhere
  • Automatic Instrumentation (just mention it exists, link to the content)
  • Instrumentation libraries (just mention it exists, link to the content)
  • Configure your HTTP propagator (b3, Baggage) <-- should this really be in here though?
  • Use the OpenTelemetry Collector for traces
• Automatic Instrumentation
  • Introduce autoinstrumentation (new content)
  • How to use the agent, with an example (same content as in examples/autoinstrumentation)
  • Some Agent configuration, if applicable
  • Link to manual instrumentation as a next step
• Instrumentation libraries
  • Introduce the concept
  • How to use an instrumentation library (same content as exists in Getting Started today)
  • Additional configuration, if applicable
  • Link to manual instrumentation as a next step
• Manual instrumentation
  • Introduce concept, link back to autoinstrumentation and instrumentation libraries as well
  • Create a new span
  • Get and modify a span
  • Create nested/child span (lift a bit from getting started)
  • Add attributes to spans (lift a bit from getting started)
  • Baggage (existing content)
• FAQ and cookbook
  • Manually set span context
  • Use multiple tracer providers with different resource

That's..quite a lot, so I'm more than happy to just do a tiny bit of this. That said, most of the content already exists in some form here, and I don't think it's a whole lot of work to futz around with the structure and fill in some gaps.

What do you think?

[lzchen]

The organization of the topics looks great. Just a couple of questions.

1. When you refer to "docs", do you mean the content in docs or the content in readthedocs?

2. What I'd like to propose is that "Getting Started" is broken up into 5 sections, in this order:

Does the content listed above fall under "Getting Started"? Or is this what encapsulates the entire content?

3. How specific will the Instrumentation libraries section be? Will the information in the contrib readthedocs be linked somehow?

[cartermp]

Awesome!

When you refer to "docs", do you mean the content in docs or the content in readthedocs?

Hmm, aren't they the same? It's the same content/structure AFAIK.

Does the content listed above fall under "Getting Started"? Or is this what encapsulates the entire content?

I'm thinking It'd be under that top-level node, yes. Other top-level nodes don't really have much conceptual content; they're a little more like reference content (aside from the examples node).

One question that comes up for me is if that top-level node should still be called Getting Started. I could see it staying that way or being named differently ("Conceptual content" or "Using OpenTelemetry with Python" could be candidate names). But I'm cool with whatever folks are most comfortable with.

How specific will the Instrumentation libraries section be? Will the information in the contrib readthedocs be linked somehow?

Great question. Probably not too specific - maybe working through one example that also shows how to configure? But absolutely, yes, linking out to the contrib readthedocs.

[lzchen]

I think "Using OpenTelemetry with Python" would be an appropriate header name. And each section (the five listed) would fall under this header. In the future we may add even more sections as more common situations arise.

I will also add this to the list of topics talked about in the upcoming SIG to get an idea of people's opinions.

[cartermp]

Awesome, thanks! And if it's approved, I can be assigned to do the work. More than happy to see it through. And just to reiterate, I'm also perfectly happy to just adding and augmenting existing content if folks feel that's better right now.

[lzchen]

@cartermp
The SIG has agreed to these changes and we think it will be a great improvement. Just be careful that if we change any of the navigation, that the links will be the same/backwards compatible.

Feel free to split up this task to seperate issues so we can track them iteratively.

[cartermp]

I think I'll close this one out. Some of the stuff about getting started has changed from this issue, mostly to be uniform w.r.t. the plan for all languages, but the content from the original docs + more has now been added to relevant sections in the docs. I think the remaining bit will be to document how to switch context propagation formats, which I'll tee up pretty shortly.