Skip to content

docs(elasticsearch): use native Java tracing across client majors - #1084

Merged
nik13 merged 4 commits into
mainfrom
docs/elasticsearch-java-native-tracing
Nov 2, 2026
Merged

nik13 merged 4 commits into
mainfrom
docs/elasticsearch-java-native-tracing

Conversation

@nik13

@nik13 nik13 commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Replace the incomplete Elasticsearch Java snapshot-wrapper setup with the client's native OpenTelemetry instrumentation and published Maven Central dependencies.
  • Provide executable synchronous, asynchronous, and KNN searches, Future AGI authentication/resource configuration, shutdown flushing, and reuse of an application's existing SDK.
  • Keep the published com.futureagi:traceai-java-elasticsearch:1.0.1 wrapper as optional retrieval enrichment on its supported 8.12.0 client. Its KNN builder lambda throws ClassCastException on 9.5.5; the guide explicitly directs 9.x users to native tracing instead. No wrapper API is removed or changed.
  • Keep search-body capture disabled and explain the remaining index/URL/error metadata. Native-only searches emit one database span; optional enrichment produces a distinct retrieval parent plus database child.

Verification

  • Failing-first page contract reproduced the missing native setup and obsolete JitPack snapshot dependency on current main.
  • Confirmed Maven Central's latest Elasticsearch Java client is 9.5.5 and wrapper 1.0.1 is published.
  • Network-denied local tests with Java 21: 14/14 on Elasticsearch 8.12.0 and 13/13 on 9.5.5, no skips. Tests execute the real client against loopback Elasticsearch responses and a protobuf OTLP receiver, including exact extracted examples packaged without the optional wrapper/test dependencies.
  • Verified synchronous/asynchronous success and errors, application parent context, KNN, global SDK initialization, content exclusion, plain/gzip OTLP, Future AGI headers/resources, and batch shutdown.
  • All seven example payloads pass the real production ingestion converter from future-agi/future-agi@215b19543a47de8c7ae7e8dc452dc267440e5c8d. Native spans retain database attributes as generic (unknown) observations, not invented semantic retrievers. The optional retrieval parent preserves its semantic kind and parentage.
  • Final-head CI is green: all four Java 17/21 × Elasticsearch 8.12.0/9.5.5 jobs pass (54 tests total, no skips), plus documentation build and link audit. Native matrix run · Documentation checks.
  • Dependencies resolve before tests run in a loopback-only network namespace. Follow-up commits fixed the runner/sudo Maven-cache boundary and a test that sampled native async spans before their completion callback exported them. Workflow validation also passes actionlint.
  • Documentation integration tests 18/18, production build, and isolated Chrome rendering/link checks pass. Existing site-wide Pagefind warnings remain unrelated.

Scope

Documentation and regression coverage only; no SDK release or product change. No real Elasticsearch cluster, Future AGI Cloud credentials, or customer data was used. The production converter check does not claim live authentication, storage, or UI ingestion. No new product screenshot was fabricated.

🤖 Generated with Claude Code

nik13 and others added 4 commits November 2, 2026 02:40
Replace the incomplete snapshot-wrapper setup with published native OpenTelemetry dependencies. Exercise exact sync, async and KNN snippets on 8.12.0 and 9.5.5 through loopback OTLP and the production converter; retain the released wrapper only for its supported retrieval enrichment.

Co-Authored-By: Claude Code <noreply@anthropic.com>
sudo changes Java user.home independently of HOME; use the same Maven repository for dependency resolution and network-isolated execution.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Resolve RUNNER_TEMP at step execution and pass the path through GITHUB_ENV; runner context is unavailable in job-level env. Validated with actionlint.

Co-Authored-By: Claude Code <noreply@anthropic.com>
The client future can complete before native instrumentation finishes exporting its span. Bound the wait for the first export rather than assuming response completion makes it immediately visible; keep exact span-count and parentage assertions.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@nik13
nik13 merged commit 1d68e6e into main Nov 2, 2026
6 checks passed
@nik13
nik13 deleted the docs/elasticsearch-java-native-tracing branch November 2, 2026 11:28
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