Add autoinstrumentation doc

[cartermp]

Contributes to open-telemetry/opentelemetry.io#972

I also tweaked the document order here. I thought it was weird that Context Propagation and Span Events came before Manual Instrumentation. Perfectly happy to revert that change and any other little tweaks I made though.

[arielvalentin]

@cartermp Thank you for this contribution!

We (@robbkidd and I) decided to defer writing up documentation for customizing automatic instrumentation libraries when coming up with our initial draft because we thought it would be best to drive our users towards the goal of minimal customization to start. We also felt providing details about customizations up front would make this burdensome for our users.

We also tried to steer folks away from Manual Instrumentation, since we hope that the experience of using the SDK + auto-instrumentation would lead to generating insights quickly without requiring manual intervention from developers. Less code + deeper insights == win!

With that in mind we chose Context Propagation as the next step since it would flow into being able to provide our users with what we unlocks the power of OTEL Distributed Tracing.

Unlike the auto-instrumentation libraries, Span Events are part of the stable API and we hope to steer our users towards preferring them over other signals clears throat logs.

All that being said, I personally still feel like we need an "advanced configuration" section, where users who are comfortable adjusting the SDK configuration could use as a reference guide.

So my personal preference here would be to keep the original flow we had in place but incorporate the updates you have submitted as part of this PR in a "Advanced Configuration" section of sorts.

Thoughts?

[cartermp]

@arielvalentin Happy to adjust as per preferences here. I will do the following:

• Revert the structural tweaks
• Make sure the Getting Started guide links to this new document, and in the context of "to learn more about how to configure automatic instrumentation, see ..." or something like that

Does that work?

[cartermp]

Also, I'd like to start a discussion about future contributions:

This isn't squarely a otel-ruby problem, but in my work the number one issue being raised by our sales and customer success teams is that opentelemetry docs - specifically on how to do various things with different languages - is extremely sparse. This has been consistently the number one problem for a few months now. So, I wanna help solve that problem!

The major theme is that content and a sprinkling of guidance is just missing, or hard to find, or not linked to samples, or using an example that doesn't make sense. Some of that problem does come down to docs organization and preferences around guidance. I have my own opinions about that, but I'm more focused on making sure there is adequate conceptual content with code examples for major topics (auto instrumentation, getting current span, adding attributes to span, starting new span, starting nested span, getting/setting a trace properly, adding a span link, adding a span event, setting baggage, sampling, some config, etc.) - and figuring out the "how do we organize this?" problem incrementally.

So before I try and throw a bunch more PRs your way, maybe it's good to cover generally what I'd like to propose, and see where we align, so myself (and hopefully others!) can just get cranking on some more contributions.

[arielvalentin]

@cartermp thank you very much for stepping in to help! When we started working on our initial documentation, @robbkidd and I struggled with writing just enough documentation and writing Head First OpenTelemetry and based on feedback you've been hearing it seems like we are still coming up short to consider it to be just enough.

figuring out the "how do we organize this?" problem incrementally

Although I agree that we will provide our users with a better experience by providing more content, I think it would be a good idea to engage folks as soon as possible in the docs repository to produce an outline or template for each language implementation to create a consistent experience for our users.

Does that sound reasonable?

cc: #775

[cartermp]

@arielvalentin all feedback accounted for!

based on feedback you've been hearing it seems like we are still coming up short to consider it to be just enough.

Heh, well the good news is that it's pretty universal 😆 😭 - but also straightforward to address! Well, at least in terms of adding content so that it can be picked up by Google and linked to.

I can make this a discussion item in this week's docs SIG. We have some items being tracked that hint at a general approach for each language SDK (e.g., open-telemetry/opentelemetry.io#964) but no concrete proposal along the lines of "these are each of the major topics that are covered in each language SDK section and here's how they are roughly organized". I can propose that upstream and tag you and others.

In the interim, provided it's just in small-ish increments (and not messing with the existing structure here), would you be comfortable still taking PRs? For example, adding a small section in the manual instrumentation doc that shows how to create a nested span, or a span link.

[arielvalentin]

Thanks @cartermp for following up with the docs SIG 🎉

[ericmustin]

ty for the awesome work here @cartermp

[cartermp]

Looks like this one is passing CI - anything holding up a merge?

[ericmustin]

@cartermp no not really just a lot of PTO / OOO from folks here, we'll be sure to get this merged when everyone is back in action 2022

[chalin]

@cartermp - please see the following comment regarding filename conventions: open-telemetry/opentelemetry.io#780 (comment)