Refactor java SDK and configuration

[jack-berg]

This is the first PR in what will be a multi-step reworking of the Java docs, as discussed in #4853 and the related doc.

Disclaimer: Refactoring docs iteratively is difficult because its hard to know where to stop. Docs develop organically over time and end with lots of interlinking and little warnings which get in the way of refactoring. For this PR, the scope I targeted was the "SDK", but this leaked into "SDK configuration" because the two are so tightly connected. It also leaked into the "Instrumentation" page which often talks about the SDK through conflated responsibilities. It also leaked into the standalone "Resources", "Exporters", and "Samplers" pages since these are SDK concepts.

What does this PR do?

• Add a new "Manage Telemetry with SDK" page
  • Standard presentation of all key user facing SDK components. Each component includes a brief description, a table of artifact coordinates of key implementations, a demonstration of programmatic configuration, and a demonstration of custom implementations.
  • This page supersedes "Sampling", "Exporters", and "Resources" pages
  • This page supersedes SDK content sprinkled through the "Instrumentation" page
• Rework "Configuration" page into "Configure the SDK"
  • Discuss programmatic configuration interface
  • Discuss zero-code SDK autoconfigure module, and recommend to users
    • Enumerate all environment variables / system properties
    • Explain how users can layer on programmatic configuration when properties are insufficient
    • Explain SPI extension points, and for each SPI, provide: a brief description, a table of artifact coordinates of key implementations, and a demonstration of an implementation.
  • Discuss declarative configuration (i.e. file configuration), with caveat that its under development

There is lot of content in this PR, but the principles are simple and scalable. The quantity of content reflects the essential complexity of the project, and is required in order for completeness. I recommend reviewing by looking at the rendered website.

I have future PRs planned for:

• Add "Learn the basics" page introducing concepts and routing users to correct pages
• Rework "Instrumentation" page "Use the API", with consistent framing and consistent usage of code snippets.
• Rework "Libraries" page into "Instrument an application", describing different instrumentations categories and routing users to appropriate places for installation instructions
• Add "Add Telemetry for Library Developers" page establishing idiomatic practices for library authors looking to adopt OpenTelemetry natively
• And more...

cc @open-telemetry/java-approvers, @open-telemetry/java-instrumentation-approvers

Preview: https://deploy-preview-4966--opentelemetry.netlify.app/docs/languages/java/

[jack-berg]

Corresponding PR with supporting code snippets: open-telemetry/opentelemetry-java-examples#455

[zeitlinger]

great - so much clearer

[zeitlinger]

the term zero-code already has a meaning: https://opentelemetry.io/docs/concepts/instrumentation/zero-code/

maybe "declarative"?

[jack-berg]

I'm trying to rebrand file configuration as "declarative configuration" here: open-telemetry/opentelemetry-specification#4128

Since SDK autoconfigure combines environment variable / system property configuration AND declarative configuration in one module, calling it "declarative configuration" is probably not a great name.

Maybe just "SDK autoconfigure"? Also open to other ideas..

[theletterf]

Fantastic work! Leaving a first round of suggestions.

[jack-berg]

Thanks for the reviews @theletterf, @zeitlinger!

[jaydeluca]

huge improvement, bravo! 👏

Left some ideas and suggestions for consideration.

[svrnm]

Finally, I found some time to take a look, but I see already that @theletterf , @jaydeluca and @zeitlinger are providing reviews and great feedback!

Awesome work, looking forward to see this land.

[svrnm]

Made it work again, using the changes as suggested above.

@open-telemetry/java-approvers @open-telemetry/docs-approvers PTAL! Would be great to ship this if there are no more major objections :-)

[chalin]

@open-telemetry/docs-maintainers - a reminder that an en PR shouldn't be updating non-en pages.