Repository navigation
feat(java): Quarkus LangChain4j to Future AGI recipe example (TH-8270) - #266
Merged
Merged
Conversation
java/examples/quarkus-langchain4j-example: a Quarkus command-mode app with one @RegisterAiService and one @tool. Quarkus LangChain4j creates the spans, quarkus-opentelemetry exports them over OTLP http/protobuf to {FI_BASE_URL}/tracer/v1/traces with X-Api-Key/X-Secret-Key and resource project_name/project_type. No traceAI module, no traceai-langchain4j. Tested: quarkus-langchain4j 1.14.2 on Quarkus 3.33.3.1 (primary), 1.8.2 on Quarkus 3.27.2 (PRD pin, live run only). Application code to copy, with tests: - FutureAgiTracingDefaults: ERROR status on failed model calls and AI service calls (upstream records the exception but leaves the status UNSET), error text only with fi.export-error-details=true, removes host.name (Quarkus adds it after the resource config and the disabled-keys filter). - ToolErrorStatus: ERROR status on a failed tool span (1.12.0+). application.properties keeps content off and drops exception events (quarkus.otel.span.event.count.limit=0, needs OTel SDK 1.51+). 14 tests against a scripted OpenAI-compatible server and a stand-in OTLP collector; run_e2e.sh adds the negative check (no quarkus-opentelemetry, no export) and the live run. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
nik13
marked this pull request as ready for review
October 21, 2026 22:19
Co-Authored-By: Claude Code <noreply@anthropic.com>
Plan only supported packages present at the head. Preserve Python and LiveKit coverage; use frozen dependencies, pinned toolchains and a fail-closed aggregate. No vendor, publication or deployment credentials. Co-Authored-By: Claude Code <noreply@anthropic.com>
Temurin labels the build metadata with an LTS suffix; pin the unambiguous 21.0.8 release instead of an unavailable 21.0.8+9 variant. Co-Authored-By: Claude Code <noreply@anthropic.com>
Keep independently landing integration workflows coherent by exposing the pinned Corepack shim to later build steps. No planner, path selection, test command, or result gate changes. Co-Authored-By: Claude Code <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
TH-8270 (parent TH-8103). Adds
java/examples/quarkus-langchain4j-example: a Quarkus command-mode app with one@RegisterAiServiceand one@Toolwhose own Quarkus LangChain4j spans are exported to Future AGI byquarkus-opentelemetry. Recipe only, per the approved architecture: no traceAI module, no Future AGI Quarkus extension, notraceai-langchain4j, nothing else in the repo touched. Pairs with the docs PR in future-agi/docs (pageintegrations/traceai/java/quarkus-langchain4j): future-agi/docs#982What it ships:
application.properties: OTLPhttp/protobufto${FI_BASE_URL}/tracer(Quarkus appends/v1/traces),X-Api-Key/X-Secret-Keyheaders, resourceproject_name+project_type=observe, compression none, the four content flags written out asfalse,quarkus.otel.span.event.count.limit=0.FutureAgiTracingDefaults+ToolErrorStatus(application code customers copy):ERRORstatus on failed AI service / model / tool spans, error text only withFI_EXPORT_ERROR_DETAILS=true, removeshost.name.DefaultExportTest9,ContentOptInTest2,UpstreamDefaultsTest3) against a scripted OpenAI-compatible server and a stand-in OTLP collector: hierarchy (one trace, AI service root, model + tool spans as its children, REST client spans under model spans), gen_ai attributes and tokens, no token attributes without usage,POST /tracer/v1/traces+application/x-protobuf+ no gzip + both headers, resource with project and nohost.*/process.*, content off, ERROR without error text on model and tool failures, Future AGI keys never sent to the model, provider key never exported, opt-in exports prompt/completion/tool args/result and the error message, and three upstream-behaviour pins (Quarkus addshost.name; upstream leaves failuresUNSETwith message + stack trace events; an endpoint ending in/v1/tracesis doubled).run_e2e.sh: tests, negative check (built withoutquarkus-opentelemetry, nothing exported), live run (tool call, failing call, opt-in, batch-processor flush on exit).How to run
Versions
io.quarkiverse.langchain4j:quarkus-langchain4j-bom1.14.2 (latest stable on Maven Central, published 2026-10-15; 1.15.0.CR1 and 2.0.0.Beta1 are pre-releases) on Quarkus platform 3.33.3.1 (the version 1.14.2 declares), OpenTelemetry SDK 1.57.0, LangChain4j 1.20.2.openjdk@21), Maven 3.10.0. JVM mode.quarkus-langchain4j-openaiagainst the local CLIProxy OpenAI-compatible endpoint, modelgpt-6-luna(real model calls with a real tool call). Failure case: modelno-such-model-th8270, which the endpoint rejects with HTTP 400model_not_found.E2E evidence (local self-hosted Future AGI, 2026-10-16)
The packaged app (
java -jar target/quarkus-app/quarkus-run.jar), configured only through the shippedapplication.properties+FI_*/OPENAI_*environment, exporting tohttp://localhost:14338/tracer/v1/traces.fi_verify --project th8103-rest-quarkus-langchain4j --min-spans 2 --expect-type llm --expect-type tool: PASS, 4 traces / 18 spans (two runs: first run and final run on the committed head), 2 ERROR tracesFirst run, same project: 45adb343-ca02-6f15-ea28-d7ca6f024a34 (tool call), 39028eb8-a6ad-1d54-3194-d30ef90a00c0 (ERROR).
th8103-rest-quarkus-langchain4j-optin(fourinclude-*flags +FI_EXPORT_ERROR_DETAILS=true): PASS, traces f079b177-84bb-1727-2438-d34eeac11e87, 7e976b18-9903-26f2-ab53-b7d7ac06719d, 4cd094ce-9beb-fad8-2cbf-87d2ac27de4f, 6a3becd9-45ed-1a2d-b5a6-8d84ad898ef6; the ERROR spans carry the provider error text as status message.quarkus.otel.simple=false), one question, normal exit -> projectth8103-rest-quarkus-langchain4j-batch: PASS, all 6 spans of traces 52f04595-bdee-0800-ee12-1decf6f3ee79 and 10d04a72-044d-819c-bae9-3c70291464cf.quarkus-opentelemetry(-DnoOtel) sent 0 requests to a stub collector.th8103-rest-quarkus-langchain4j-v182b: base check PASS (traces 4c6f7c6e-9adf-e62b-78d6-874ed7d407d6, 2b2ab3cb-2bb3-dadc-6ed8-08946cc84bc6, ERROR on AI service + model span), but--expect-type llmFAILS: model spans areunknownwithout tokens (finding 5).completion gpt-6-lunaspans with tokens, the tool span and REST client children.Privacy proof
Unique marker in every question (
What is the weather in Paris<marker>?, also in the failing call), plus needles for the provider error text (unknown provider for model), the exception class, a stack frame (at dev.langchain4j), the system prompt, the tool arguments and tool result text, the host name, the OS user name, the provider key and both Future AGI keys. Scanned every column (toString(tuple(*))incl.resource_attrs,span_events,attrs_*,status_message) of ClickHousespans,traces,trace_sessions,spans_per_session,end_users,property_catalog.observed_attribute_values/_keys, androw_to_jsonof all 28 Postgrestrace*tables with aproject_idplus thetracer_projectrow.th8103-rest-quarkus-langchain4j, 18 spans;-batch, 12 spans): every needle in 0 rows of all tables. Nohost.name, noprocess.*in the resource.-optin): marker in 4 span rows + 6 attribute-catalog rows, system prompt, tool arguments, tool result and the error text present. Keys, host name, user name, stack frames still 0.[{"name":"exception","timestamp":...}]on the 3.27 leg, where events were on), so exception messages and stack traces are never stored; the recipe still keeps them off the wire.Findings (what changed vs the PRD / architecture / docs draft; all version-tested or source-read and cited)
/v1/tracestoquarkus.otel.exporter.otlp.traces.endpointtoo (VertxHttpSender.TRACES_PATH, Quarkus 3.33.3.1 source; asserted inUpstreamDefaultsTest). The architecture/docs-draft value.../tracer/v1/tracesposts to/tracer/v1/traces/v1/traces(404 on the local collector). The recipe uses{base}/tracer.host.nameto the resource afterquarkus.otel.resource.attributesand after thedisabled-keysfilter (AutoConfiguredOpenTelemetrySdkBuilderCustomizer.ResourceCustomizer; OTel autoconfigure filters before customizers), so config cannot remove it. The example shipsDropHostName(lowest CDI priority so it runs after Quarkus' customizer; with equal priority the order was random and the first test run leaked it).recordExceptions on the AI service, model and tool spans but never setsERROR(1.14.2SpanWrapper,SpanChatModelListener,ToolSpanWrapper). PRD AC-08 needs app code:FutureAgiTracingDefaults(documentedChatModelSpanContributor+AiServiceErrorEventobserver) andToolErrorStatus(ToolSpanContributor, 1.12.0+).exception.message+ fullexception.stacktraceon the wire by default.quarkus.otel.span.event.count.limit=0drops them. It needs OTel SDK 1.51+: Quarkus 3.27.2 (SDK 1.44.1) refuses to start with it.quarkus.otel.attribute.count.limitdoes not help (SdkSpan.recordExceptionsizes the event with the span limit).gen_ai.operation.nameand usegen_ai.usage.prompt_tokens/completion_tokens(not read by the collector), so they show asunknownwithout tokens. The current names appear in 1.11.0 (source jars 1.10.0 vs 1.11.0).quarkus.langchain4j.tracing.include-prompt|completion|tool-arguments|tool-result, default false, runtime config) are the same in the 1.8.2 and 1.14.2 sources (TracingConfig), as the PRD asked (V-B). Opt-in content is stored as span attributes; Future AGI's Input/Output columns stay empty.OtlpExporterConfig,MetricsBuildConfig,LogsBuildConfig); tests assert only/tracer/v1/tracesis hit, withoutContent-Encoding.Tool usage requires chat memorybuild error), so the example keeps the default request-scoped memory.STANDIN
None for the integration itself: real Quarkus LangChain4j 1.14.2, real Quarkus OpenTelemetry exporter, real local Future AGI. The model is the local CLIProxy OpenAI-compatible endpoint (BRIEF-approved model source), not api.openai.com. The 14 unit tests use a scripted OpenAI-compatible server and a stand-in OTLP collector by design.
Limitations / unsupported
JVM only (native image not built). One provider extension (OpenAI-compatible) run; streaming AI services, REST endpoints in front of the AI service, gRPC export and the hosted
api.futureagi.comwere not tested. The AI service span is typeunknownwith no input/output/token totals. The TH-8339 shared harness is not ondev(only open PR #229, Python fixtures), so the conformance assertions live in this example's tests; nothing was copied from it. Micrometer metrics and CDI observability events are not exported (traces only).Nav suggestion (for the docs page)
Integrations > traceAI > Java, title Quarkus LangChain4j,
/docs/integrations/traceai/java/quarkus-langchain4j(set in the docs nav PR, not here).BLOCKED-ON
None. Everything above ran locally against the real upstream and the local Future AGI.
🤖 Generated with Claude Code