Refactor java instrumentation

[jack-berg]

Related to #5211. Followup to #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 #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

[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!

[svrnm]

@jack-berg can you check with @open-telemetry/java-approvers that at least one of them is also taking a look through the changes?

[jack-berg]

Thanks for the review @jaydeluca 🙏

[svrnm]

overall lgtm, there are a few open discussions we should close and then wrap this up :-)

[jack-berg]

We have one remaining open conversation here. Discussing here because that thread is buried and hard to find.

I feel like the easiest path forward is to just remove the links from the translated versions of libraries to the now removed java sections, like I had originally done. Probably not a solution to the general case, but in this case, there are no translated versions of the instrumentation page being modified, and the link probably shouldn't have been there in the first place.

WDYT?

[svrnm]

We have one remaining open conversation here. Discussing here because that thread is buried and hard to find.

I feel like the easiest path forward is to just remove the links from the translated versions of libraries to the now removed java sections, like I had originally done. Probably not a solution to the general case, but in this case, there are no translated versions of the instrumentation page being modified, and the link probably shouldn't have been there in the first place.

WDYT?

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.