Skip to content

feat(java): Quarkus LangChain4j to Future AGI recipe example (TH-8270) - #266

Merged
nik13 merged 5 commits into
devfrom
feat/th-8270-quarkus-langchain4j
Oct 27, 2026
Merged

nik13 merged 5 commits into
devfrom
feat/th-8270-quarkus-langchain4j

Conversation

@nik13

@nik13 nik13 commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

TH-8270 (parent TH-8103). Adds java/examples/quarkus-langchain4j-example: a Quarkus command-mode app with one @RegisterAiService and one @Tool whose own Quarkus LangChain4j spans are exported to Future AGI by quarkus-opentelemetry. Recipe only, per the approved architecture: no traceAI module, no Future AGI Quarkus extension, no traceai-langchain4j, nothing else in the repo touched. Pairs with the docs PR in future-agi/docs (page integrations/traceai/java/quarkus-langchain4j): future-agi/docs#982

What it ships:

  • application.properties: OTLP http/protobuf to ${FI_BASE_URL}/tracer (Quarkus appends /v1/traces), X-Api-Key/X-Secret-Key headers, resource project_name + project_type=observe, compression none, the four content flags written out as false, quarkus.otel.span.event.count.limit=0.
  • FutureAgiTracingDefaults + ToolErrorStatus (application code customers copy): ERROR status on failed AI service / model / tool spans, error text only with FI_EXPORT_ERROR_DETAILS=true, removes host.name.
  • 14 tests (DefaultExportTest 9, ContentOptInTest 2, UpstreamDefaultsTest 3) 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 no host.*/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 adds host.name; upstream leaves failures UNSET with message + stack trace events; an endpoint ending in /v1/traces is doubled).
  • run_e2e.sh: tests, negative check (built without quarkus-opentelemetry, nothing exported), live run (tool call, failing call, opt-in, batch-processor flush on exit).

How to run

export JAVA_HOME=<jdk 17+>     # 21 tested
cd java/examples/quarkus-langchain4j-example
./run_e2e.sh                   # 14 tests + negative check, no keys
FI_API_KEY=... FI_SECRET_KEY=... FI_BASE_URL=http://localhost:14338 FI_PROJECT_NAME=quarkus-demo \
OPENAI_API_KEY=... OPENAI_BASE_URL=https://api.openai.com/v1/ OPENAI_MODEL=gpt-4o-mini ./run_e2e.sh   # + live steps
QLC4J_VERSION=1.8.2 QUARKUS_VERSION=3.27.2 ./run_e2e.sh                                             # older pair, tests skipped

Versions

  • Primary: io.quarkiverse.langchain4j:quarkus-langchain4j-bom 1.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.
  • Matrix leg (PRD pin): 1.8.2 on Quarkus 3.27.2 (OpenTelemetry SDK 1.44.1), live run only. The PRD pin is stale: see findings 5 and 6. Re-pinned to 1.14.2 per the coordinator decision.
  • OpenJDK 21.0.12 (Homebrew openjdk@21), Maven 3.10.0. JVM mode.
  • Model: quarkus-langchain4j-openai against the local CLIProxy OpenAI-compatible endpoint, model gpt-6-luna (real model calls with a real tool call). Failure case: model no-such-model-th8270, which the endpoint rejects with HTTP 400 model_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 shipped application.properties + FI_* / OPENAI_* environment, exporting to http://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 traces

trace c8ae2b99-3f7b-b4fe-fc20-765d34b86b7e (6 spans)
- [unknown] langchain4j.aiservices.Assistant.chat (3978ms)
  - [llm] completion gpt-6-luna model=gpt-6-luna tok=388/40 (2178ms)
    - [unknown] POST /chat/completions (1814ms)
  - [tool] langchain4j.tools.currentWeather (5ms)
  - [llm] completion gpt-6-luna model=gpt-6-luna tok=442/25 (1722ms)
    - [unknown] POST /chat/completions (1716ms)

trace 376a9e94-6571-d726-0b70-fa6a0b51523f (3 spans)
- [unknown] langchain4j.aiservices.Assistant.chat status=ERROR: (331ms)
  - [llm] completion no-such-model-th8270 model=no-such-model-th8270 status=ERROR: (269ms)
    - [unknown] POST /chat/completions (13ms)
PASS

First run, same project: 45adb343-ca02-6f15-ea28-d7ca6f024a34 (tool call), 39028eb8-a6ad-1d54-3194-d30ef90a00c0 (ERROR).

  • Opt-in project th8103-rest-quarkus-langchain4j-optin (four include-* 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.
  • Flush on shutdown: batch-processor build (quarkus.otel.simple=false), one question, normal exit -> project th8103-rest-quarkus-langchain4j-batch: PASS, all 6 spans of traces 52f04595-bdee-0800-ee12-1decf6f3ee79 and 10d04a72-044d-819c-bae9-3c70291464cf.
  • Negative: the same app built without quarkus-opentelemetry (-DnoOtel) sent 0 requests to a stub collector.
  • 1.8.2 / Quarkus 3.27.2 leg, project 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 llm FAILS: model spans are unknown without tokens (finding 5).
  • UI screenshots checked: trace list shows the ERROR and UNSET traces; trace view shows the AI service root, two completion gpt-6-luna spans 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 ClickHouse spans, traces, trace_sessions, spans_per_session, end_users, property_catalog.observed_attribute_values / _keys, and row_to_json of all 28 Postgres trace* tables with a project_id plus the tracer_project row.

  • Defaults (th8103-rest-quarkus-langchain4j, 18 spans; -batch, 12 spans): every needle in 0 rows of all tables. No host.name, no process.* in the resource.
  • Opt-in (-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.
  • Wire level (tests, every byte the stand-in collector received, headers included): no marker, no provider key, no error body, no stack frame or exception type, no host name, home directory, working directory or user name.
  • Future AGI stores span events as name + time only ([{"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)

  1. Endpoint: Quarkus appends /v1/traces to quarkus.otel.exporter.otlp.traces.endpoint too (VertxHttpSender.TRACES_PATH, Quarkus 3.33.3.1 source; asserted in UpstreamDefaultsTest). The architecture/docs-draft value .../tracer/v1/traces posts to /tracer/v1/traces/v1/traces (404 on the local collector). The recipe uses {base}/tracer.
  2. host.name: Quarkus always adds host.name to the resource after quarkus.otel.resource.attributes and after the disabled-keys filter (AutoConfiguredOpenTelemetrySdkBuilderCustomizer.ResourceCustomizer; OTel autoconfigure filters before customizers), so config cannot remove it. The example ships DropHostName (lowest CDI priority so it runs after Quarkus' customizer; with equal priority the order was random and the first test run leaked it).
  3. Status: Quarkus LangChain4j recordExceptions on the AI service, model and tool spans but never sets ERROR (1.14.2 SpanWrapper, SpanChatModelListener, ToolSpanWrapper). PRD AC-08 needs app code: FutureAgiTracingDefaults (documented ChatModelSpanContributor + AiServiceErrorEvent observer) and ToolErrorStatus (ToolSpanContributor, 1.12.0+).
  4. Exception events: those calls put exception.message + full exception.stacktrace on the wire by default. quarkus.otel.span.event.count.limit=0 drops them. It needs OTel SDK 1.51+: Quarkus 3.27.2 (SDK 1.44.1) refuses to start with it. quarkus.otel.attribute.count.limit does not help (SdkSpan.recordException sizes the event with the span limit).
  5. PRD pin 1.8.2 is stale for Future AGI: its model spans have no gen_ai.operation.name and use gen_ai.usage.prompt_tokens/completion_tokens (not read by the collector), so they show as unknown without tokens. The current names appear in 1.11.0 (source jars 1.10.0 vs 1.11.0).
  6. Content property names (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.
  7. Compression already defaults to none and metrics/logs export to off in Quarkus 3.33 (OtlpExporterConfig, MetricsBuildConfig, LogsBuildConfig); tests assert only /tracer/v1/traces is hit, without Content-Encoding.
  8. Tool usage requires chat memory in Quarkus LangChain4j (Tool usage requires chat memory build 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.com were not tested. The AI service span is type unknown with no input/output/token totals. The TH-8339 shared harness is not on dev (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

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
nik13 marked this pull request as ready for review October 21, 2026 22:19
nik13 and others added 4 commits October 26, 2026 11:05
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>
@nik13
nik13 merged commit 20a274c into dev Oct 27, 2026
9 checks passed
@nik13
nik13 deleted the feat/th-8270-quarkus-langchain4j branch October 27, 2026 05:47
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