Refactor java instrumentation

[jack-berg]

Related to open-telemetry/opentelemetry-go#5211. Followup to open-telemetry/opentelemetry-go#4966.

This PR breaks up and adds coherence to the topics currently discussed in Instrumentation:

• Add a new "Record Telemetry with API" page
  • Standard presentation of all key user facing API components. Each component includes a brief description, links to javadoc, links to relevant concept resoruces, and a code snippet exploring API usage.
  • This page supersedes and expands on the "Traces" and "Metrics" sections from the "Instrumentation" page.
• Rework "Instrumentation" page into "Instrumentation ecosystem"
  • Discuss the various categories of instrumentation in the OpenTelemetry Java ecosystem, linking out to relevant resources.
  • Discuss cross-cutting instrumentation topics, including context propagation, semantic conventions, and the special case of logging instrumentation.

The PR for the code snippet additions to opentelemetry-java-examples is available here: open-telemetry/opentelemetry-java-examples#498

There is a lot of content in this PR, but like open-telemetry/opentelemetry-go#4966, the principles are simple and scalable. I recommend reviewing by looking at the rendered website. Links to previews for main pages involved:

• Instrumentation ecosystem
• Record Telemetry with API

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

---

Redirect test:

• https://deploy-preview-5276--opentelemetry.netlify.app/docs/languages/java/libraries/

[chalin]

@jack-berg - please rebase and resolve conflicts before we proceed:

[jack-berg]

@jack-berg - please rebase and resolve conflicts before we proceed:

I've merged main rather than rebase. I generally avoid rebasing since it overwrites git history and requires force pushing. If this repo prefers rebasing for some reason, I'm happy to do that.

[jack-berg]

@chalin / @svrnm any idea what's happening with a the deploy to netlify? It almost seems like its in a corrupt state, since this PR currently doesn't touch the submodules yet those seem to be the cause of the issue:

[chalin]

@jack-berg - please rebase and resolve conflicts before we proceed:

I've merged main rather than rebase. I generally avoid rebasing since it overwrites git history and requires force pushing. If this repo prefers rebasing for some reason, I'm happy to do that.

Yes rebase from a freshly updated upstream main. Otherwise, we can get wonky issues arise when the PR rooted too far behind, for example: #5270 (review)

[chalin]

@chalin / @svrnm any idea what's happening with a the deploy to netlify? It almost seems like its in a corrupt state, since this PR currently doesn't touch the submodules yet those seem to be the cause of the issue: ...

This is the kind of wonkiness that can happen. Please rebase from a freshly updated upstream main and we'll reassess after.

[jack-berg]

This is the kind of wonkiness that can happen. Please rebase from a freshly updated upstream main and we'll reassess after.

That did the trick. Thanks!

[chalin]

We need a quick solution to merge this PR, and we need a long term solution to ensure that we can run translations while updating the (English) documentation. For the quick solution, I'd like to lean on whatever @chalin suggests to do, to get this PR merged.

From the GH checks:

blog/2023/spring-native/index.html
  target does not exist --- blog/2023/spring-native/index.html --> /docs/languages/java/libraries/

This needs to be fixed, FYI. Because all en pages must use canonical paths.
I'll update it.

As for non-en pages, a general strategy (I'm proposing) is it create a temporary link-checker ignore rule for the problematic pages, along with an issue to track its removal. I'll do that too so illustrate how that look for this PR.

[chalin]

All GH checks are passing now. I don't have time to further review the PR, so I'll lean on @svrnm et all for the rest. Thanks for pushing this forward @jack-berg! I'll mark as approved for the checking & layouts aspects.

[jack-berg]

Thanks for all your help @chalin!

[svrnm]

I love it! ❤️

[trask]

🎉