Improve Java OpenTelemetry docs

[adinauer]

Closes getsentry/sentry-java#4104 and #12619

DESCRIBE YOUR PR

Tell us what you're changing and why. If your PR resolves an issue, please link it so it closes automatically.

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.

• Urgent deadline (GA date, etc.):
• Other deadline:
• None: Not urgent, can wait up to 1 week+

SLA

• Teamwork makes the dream work, so please add a reviewer to your PRs.
• Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it.
  Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

• Checked Vercel preview for correctness, including links
• PR was reviewed and approved by any necessary SMEs (subject matter experts)
• PR was reviewed and approved by a member of the Sentry docs team

LEGAL BOILERPLATE

Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms.

EXTRA RESOURCES

• Sentry Docs contributor guide

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
sentry-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 3, 2025 0:34am

2 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
changelog	⬜️ Ignored (Inspect)	Visit Preview		Apr 3, 2025 0:34am
develop-docs	⬜️ Ignored (Inspect)	Visit Preview		Apr 3, 2025 0:34am

[codecov]

Bundle Report

Changes will increase total bundle size by 2.79kB (0.01%) ⬆️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
sentry-docs-server-cjs	10.61MB	2.8kB (0.03%) ⬆️
sentry-docs-client-array-push	9.44MB	-6 bytes (-0.0%) ⬇️

Affected Assets, Files, and Routes:

view changes for bundle: sentry-docs-server-cjs

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
1729.js	-3 bytes	1.58MB	-0.0%
../instrumentation.js	-3 bytes	911.63kB	-0.0%
9523.js	-3 bytes	887.68kB	-0.0%
../app/[[...path]]/page.js.nft.json	935 bytes	384.07kB	0.24%
../app/platform-redirect/page.js.nft.json	935 bytes	383.99kB	0.24%
../app/sitemap.xml/route.js.nft.json	935 bytes	381.96kB	0.25%

view changes for bundle: sentry-docs-client-array-push

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
static/chunks/pages/_app-*.js	-3 bytes	868.67kB	-0.0%
static/chunks/8931-*.js	-3 bytes	397.42kB	-0.0%
server/middleware-*.js	5.55kB	6.55kB	555.3% ⚠️
server/middleware-*.js	-5.55kB	1.0kB	-84.74%
static/fUAOWJKIS0qjjAU37wU_U/_buildManifest.js (New)	578 bytes	578 bytes	100.0% 🚀
static/fUAOWJKIS0qjjAU37wU_U/_ssgManifest.js (New)	77 bytes	77 bytes	100.0% 🚀
static/5pkgtGrS5eCJ-*.js (Deleted)	-77 bytes	0 bytes	-100.0% 🗑️
static/5pkgtGrS5eCJ-*.js (Deleted)	-578 bytes	0 bytes	-100.0% 🗑️

[lcian]

I like the new more digestible structure and also the fact that this is gonna be much easier to find in the docs.

Overall it feels that we're assuming that the person who's reading this is already using our SDK and not using OTEL.
I would briefly mention the benefits you get on the other way around (should be obvious but you will benefit from your spans being sent to Sentry and all our features plus error monitoring) plus how it works (just need to mention that any spans you create using OTEL APIs are automatically sent to Sentry just by installing the SDK -- that's how it works in that case right?).
Maybe there's a better way to explain this using OTEL terms that they would already be familiar with, like "adding the Sentry SDK as a dependency will autoconfigure OTEL to export telemetry data to Sentry and the SDK will act as the exporter" or something like that (not sure if that's accurate though).
This is because I assume a lot of people reading this page will likely already have an OTEL setup going (as opposed to a Sentry setup going and willing to use OTEL).

Also there's some redundancy between the pages. If I navigate to /platforms/java/opentelemetry/setup/ I see the part about the agent (/platforms/java/opentelemetry/setup/agent/) which maybe you didn't intend to have show up in both places.

[adinauer]

Overall it feels that we're assuming that the person who's reading this is already using our SDK and not using OTEL.
I would briefly mention the benefits you get on the other way around (should be obvious but you will benefit from your spans being sent to Sentry and all our features plus error monitoring) plus how it works (just need to mention that any spans you create using OTEL APIs are automatically sent to Sentry just by installing the SDK -- that's how it works in that case right?).
Maybe there's a better way to explain this using OTEL terms that they would already be familiar with, like "adding the Sentry SDK as a dependency will autoconfigure OTEL to export telemetry data to Sentry and the SDK will act as the exporter" or something like that (not sure if that's accurate though).
This is because I assume a lot of people reading this page will likely already have an OTEL setup going (as opposed to a Sentry setup going and willing to use OTEL).

I've created getsentry/sentry-java#4313 so we can further improve docs and explain what customers gain when adding Sentry.

Also there's some redundancy between the pages. If I navigate to /platforms/java/opentelemetry/setup/ I see the part about the agent (/platforms/java/opentelemetry/setup/agent/) which maybe you didn't intend to have show up in both places.

I did that on purpose to explain the agent in both locations. On the /setup page it's supposed to help figure out whether you want to use the Agent and on /setup/agent I didn't want to skip it because we're likely going to link to this page to tell customers what to use so I didn't want that page to leave out the explanation either.

[lcian]

Approving to unblock, we can improve this over time