Skip to content

docs(openinference): add native Java annotation tracing - #1094

Merged
nik13 merged 3 commits into
mainfrom
docs/openinference-java-annotations
Nov 2, 2026
Merged

nik13 merged 3 commits into
mainfrom
docs/openinference-java-annotations

Conversation

@nik13

@nik13 nik13 commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Add a Java tab to the existing OpenInference integration guide while preserving the Python recipe.
  • Use the published com.arize:openinference-instrumentation-annotation agent and one standard OTLP/HTTP exporter; no Future AGI wrapper, copied instrumentation bridge or duplicate spans.
  • Configure project routing and both authentication headers, explicit Byte Buddy startup, bounded shutdown, and input/output hiding by default.
  • Explain synchronous-method scope, Java-specific privacy configuration, exception-detail exposure and the absence of automatic model/token discovery from @LLM alone.
  • Add page regressions and loopback-only CI for JDK 17/21, OpenInference annotations 0.1.1/0.1.2 and OpenTelemetry 1.49.0/1.67.0. All installed dependencies are already published; no SDK release is required.

Validation

  • Reproduced the missing route on current main: all three new page contracts failed before the change; all three pass afterward.
  • 32 local wire cases passed across both JDKs, floor/current releases, hidden/visible content, plain/gzip OTLP, the exact documented application and a five-annotation error/exclusion fixture.
  • Asserted one export, exact parent/trace relationships, no duplicate spans, resource attributes, headers, endpoint, privacy and exception semantics.
  • All 32 captures also passed the real production collector converter at future-agi/future-agi@814b6c4e745e754dc2eeb43a4d238d318adc4daa: observation kinds, parent links, project/resource routing, content and status survive conversion.
  • Existing integration suite: 20 passed. Link audit: no broken navigation/content links. Catalog type check and Astro + Pagefind build passed.
  • Rendered the built site in an isolated Chrome session: Java/Python tab switching, all five Java code blocks and privacy content pass with no browser runtime errors; setup and privacy screenshots inspected.
  • Local tests run with outbound networking denied and synthetic credentials only. No customer data or Future AGI Cloud execution; no product screenshot is claimed.

Review fixes

  • Limit @ExcludeFromSpan to automatic argument capture; explicitly prohibit mapping sensitive or excluded parameters with @SpanMapping.
  • Restrict annotation support to non-void methods, explain class-wide transformation failure, and document leaving void methods unannotated while tracing a supported caller.
  • Both new page contracts failed before the documentation changes and now pass (5 total). Expanded the existing native CI harness to 64 local cases across JDK 17/21 and the released floor/latest dependencies, including mapped/excluded input with content on/off, String/primitive returns, annotated void failure and the unannotated-void workaround.
  • Re-ran integration tests (20 passing), catalog type check, link audit (0 broken links), Astro/Pagefind build and isolated browser rendering with assertions for both warnings. All execution tests used outbound-denied networking and synthetic credentials.
  • Merged current main normally; no force push, package release or merge of this PR.

Release scope

Documentation and its tests only. No new package, registry publication, deprecation or breaking change. This resumes the interrupted uncommitted Java draft; no earlier Java-specific PR was found.

🤖 Generated with Claude Code

nik13 and others added 3 commits November 2, 2026 07:05
Document the released annotation agent with one OTLP exporter, project routing, explicit JVM startup and Java privacy controls. Execute the guide against floor/current releases on JDK 17 and 21 in loopback-only CI.

Co-Authored-By: Claude Code <noreply@anthropic.com>
…va-annotations

Co-Authored-By: Claude Code <noreply@anthropic.com>
Document automatic-only parameter exclusion, prohibit mapping sensitive parameters, and explain class-wide transformation failure for annotated void methods. Add failing-first page contracts and released floor/latest wire controls for both behaviors.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@nik13
nik13 merged commit 5f8f284 into main Nov 2, 2026
4 checks passed
@nik13
nik13 deleted the docs/openinference-java-annotations branch November 2, 2026 16:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant