Reorganize autoconfigure docs by signal

[jack-berg]

Was having a hard time navigating the autoconfigure docs the other day because the's not a lot of organization.

This reorganizes it into sections for each signal provider (tracer provider, meter provider, logger provider) which contain configuration related to that specific signal, and a general configuration section containing signal agnostic options (exporters, resource, attribute limits, propagator).

Also generates the TOC with markdown-doc, which is what the specification uses. Didn't want to be heavy handed and introduce a bunch of automation / checking, so I just added a comment with instructions.

[codecov]

Codecov Report

Patch coverage has no change and project coverage change: +0.02% 🎉

Comparison is base (9ea8324) 91.29% compared to head (e8738ba) 91.31%.
Report is 1 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #5665      +/-   ##
============================================
+ Coverage     91.29%   91.31%   +0.02%     
  Complexity     4978     4978              
============================================
  Files           554      554              
  Lines         14731    14731              
  Branches       1376     1376              
============================================
+ Hits          13448    13451       +3     
+ Misses          887      884       -3     
  Partials        396      396              

see 4 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[mateuszrzeszutek]

Nice 👍
Do you think we could move this to the opentelemetry.io page at some point?

[trask]

Nice 👍 Do you think we could move this to the opentelemetry.io page at some point?

cc @open-telemetry/docs-maintainers

[jack-berg]

Nice 👍
Do you think we could move this to the opentelemetry.io page at some point?

Yeah I'm in favor of that if the @open-telemetry/docs-maintainers agree.

[cartermp]

Yeah, this would be great to have in docs. I'm fine with whatever process works best for you (merge here, move over, just re-add it over in docs, or something else).

[svrnm]

Yeah, this would be great to have in docs. I'm fine with whatever process works best for you (merge here, move over, just re-add it over in docs, or something else).

+1

[chalin]

Where would you want the past hosted on the website?

[jack-berg]

@chalin There's a small section dedicated to autoconfiguration on the Instrumentation > Java > Manual. We could split out a page dedicated to autoconfiguration, or expand the existing section on the Manual page.

WDYT?

[svrnm]

@jack-berg We also have a reference to the autoconfiguration here:

https://opentelemetry.io/docs/instrumentation/java/automatic/agent-config/

Just for my understanding: the Javaagent makes use of the SDK Autoconfiguration, but it can also be used in combination with manual instrumentation?

It sounds to me that it lives somewhere between manual and automatic instrumentation then (a thing we see with other languages emerging as well, e.g. sdk-node seems to live in a similar space)

Is using Auto Configuration the preferred way of doing things or should manual creation of the OpenTelemetry instance be what people default to? If so, maybe we should lead with it in the Manual Instrumentation doc?

[jack-berg]

the Javaagent makes use of the SDK Autoconfiguration, but it can also be used in combination with manual instrumentation?

Correct.

It sounds to me that it lives somewhere between manual and automatic instrumentation then (a thing we see with other languages emerging as well, e.g. sdk-node seems to live in a similar space)

That makes sense to me, especially since the agent makes reference to the section.

Is using Auto Configuration the preferred way of doing things or should manual creation of the OpenTelemetry instance be what people default to? If so, maybe we should lead with it in the Manual Instrumentation doc?

Auto Configuration is preferred. Its always been easier than programatic configuration but was hard to recommend since it was unstable until the July 1.28.0 release. Now that its stable, its the clear winner. Along with interpreting all the standard environment variables, it has various customization capabilities which allow you to do things like reference custom extension components like exporters in environment variables, and layer programmatic configuration on top of the standard environment variable. Eventually, autoconfigure will also be able to interpret configuration files in the schema described in opentelemetry-configuration. I'm sure there are use cases out there for programmatic configuration, but they're becoming increasingly rare.

[svrnm]

thanks @jack-berg!

I was planning to go over the Manual Instrumentation for Java and improve it in the same way as the one for JavaScript, so I'll see that I promote Auto Configuration accordingly.