docs: add OpenTelemetry guide for Java workloads

[Bruno Borges (brunoborges)]

Summary

The docs only said that OpenTelemetry "works as usual" on Brewlet. That hides how different it is in practice: a Brewlet image is JAR-only (no Dockerfile to copy an agent into), and some common Kubernetes injection patterns fail in runtimeClassName: brewlet pods.

This PR adds docs/opentelemetry.md, a guide that explains where the OpenTelemetry Java agent can live and how -javaagent should reach the JVM:

• Recommended: agent baked into a node JDK source image, published as its own distribution (e.g. temurin-otel) and managed by the platform team; or agent shipped in the application image as a class-path layer (/app/lib), owned by the application team.
• Alternatives: an in-app SDK/framework starter (e.g. spring-boot-starter-opentelemetry); Kubernetes image volumes for raw Pods; hostPath (works, but discouraged).
• Flag delivery: prefer jvm.args. JAVA_TOOL_OPTIONS also works; the guide covers its side effects and the informational EnvOptionsOverlap condition.
• Avoid: runtime self-attach (opentelemetry-runtime-attach), which depends on the dynamic agent loading that JEP 451 is phasing out. -javaagent at startup is not affected.
• Not supported: init containers, collector sidecars, and OpenTelemetry Operator auto-injection. The shim treats every non-sandbox container as a Brewlet app image.
• Gotchas: env vars set in the artifact's launch config override the deployment's spec.env. The agent extends the boot class path, which limits CDS/AppCDS sharing to boot-loader classes.

The page is linked from the site nav (Operate), docs/README.md and docs/observability.md.

Validation

• Tested each approach manually on a disposable kind cluster (Kubernetes v1.36, arm64, containerd 2.3) with the Brewlet 0.5.1 chart, a Temurin 21 node JDK, OpenTelemetry Java agent 2.31.1, Spring Boot 4.1.1 and an OTel Collector using the debug exporter.
  • Worked: spans with the expected service.name reached the Collector for the node JDK image, class-path layer (via jvm.args and via JAVA_TOOL_OPTIONS), Spring Boot starter, runtime attach, image volume and hostPath.
  • Failed as documented: init container, sidecar and OTel Operator injection.
• Checked JEP 451 behavior locally on JDK 26: -javaagent prints no warning; self-attach warns, and fails with -XX:-EnableDynamicAgentLoading.
• mkdocs build --strict -f site/mkdocs.yml passes, and all in-page anchors resolve.
• make site-contract-check passes.

The page states that this validation was manual and is not part of the automated E2E suite.

Compatibility and operations

None. Documentation only; no code or behavior changes.

Checklist

• Tests cover changed behavior. (N/A, docs only)
• Documentation is updated when needed.
• No credentials, proprietary data, or unrelated generated files are included.