or run

tessl search

tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-core

tessl install tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-core@1.5.0

Quarkus LangChain4j Core provides runtime integration for LangChain4j with the Quarkus framework, enabling declarative AI service creation through CDI annotations.

Observability & Events

Observability capabilities enable monitoring AI service interactions through CDI events, covering lifecycle events, tool executions, and guardrail validations.

Capabilities

@AiServiceSelector Annotation

CDI qualifier for selecting specific AI services when observing events.

// Package: io.quarkiverse.langchain4j.observability
/**
 * CDI Qualifier for selecting specific AI service for event listening.
 * Use to observe events from a particular AI service interface.
 */
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Qualifier
public @interface AiServiceSelector {
    /**
     * The AI service interface class to select.
     */
    Class<?> value();
}

AiServiceEvents Enum

Enum defining all available AI service event types.

// Package: io.quarkiverse.langchain4j.observability
/**
 * Enum of all AI service event types.
 * Each enum value corresponds to a specific event class.
 */
public enum AiServiceEvents {

    /**
     * Fired when AI service method starts.
     */
    STARTED(AiServiceStartedEvent.class),

    /**
     * Fired when response is received from model.
     */
    RESPONSE_RECEIVED(AiServiceResponseReceivedEvent.class),

    /**
     * Fired when a tool is executed.
     */
    TOOL_EXECUTED(ToolExecutedEvent.class),

    /**
     * Fired when input guardrail is executed.
     */
    INPUT_GUARDRAIL_EXECUTED(InputGuardrailExecutedEvent.class),

    /**
     * Fired when output guardrail is executed.
     */
    OUTPUT_GUARDRAIL_EXECUTED(OutputGuardrailExecutedEvent.class),

    /**
     * Fired when AI service method completes successfully.
     */
    COMPLETED(AiServiceCompletedEvent.class),

    /**
     * Fired when AI service method errors.
     */
    ERROR(AiServiceErrorEvent.class);

    /**
     * Create a listener adapter for this event type.
     *
     * @param aiServiceClass The AI service class to listen for
     * @return Listener adapter
     */
    public AiServiceListener<?> createListener(Class<?> aiServiceClass);

    /**
     * Get the event class for this event type.
     *
     * @return Event class
     */
    public Class<?> getEventClass();
}

Event Observation

Observing All Events from an AI Service

import io.quarkiverse.langchain4j.observability.AiServiceSelector;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Observes;

@ApplicationScoped
public class AssistantObserver {

    // Observe started events
    public void onStarted(
        @Observes @AiServiceSelector(MyAssistant.class) AiServiceStartedEvent event
    ) {
        System.out.println("AI service started: " + event.methodName());
    }

    // Observe completed events
    public void onCompleted(
        @Observes @AiServiceSelector(MyAssistant.class) AiServiceCompletedEvent event
    ) {
        System.out.println("AI service completed: " + event.methodName());
    }

    // Observe error events
    public void onError(
        @Observes @AiServiceSelector(MyAssistant.class) AiServiceErrorEvent event
    ) {
        System.err.println("AI service error: " + event.error().getMessage());
    }

    // Observe tool executions
    public void onToolExecuted(
        @Observes @AiServiceSelector(MyAssistant.class) ToolExecutedEvent event
    ) {
        System.out.println("Tool executed: " + event.toolName());
    }

    // Observe guardrail executions
    public void onInputGuardrail(
        @Observes @AiServiceSelector(MyAssistant.class) InputGuardrailExecutedEvent event
    ) {
        System.out.println("Input guardrail: " + event.outcome());
    }

    public void onOutputGuardrail(
        @Observes @AiServiceSelector(MyAssistant.class) OutputGuardrailExecutedEvent event
    ) {
        System.out.println("Output guardrail: " + event.outcome());
    }
}

Observing Events from All AI Services

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Observes;

@ApplicationScoped
public class GlobalObserver {

    // Observe all AI service completions regardless of service
    public void onAnyCompletion(@Observes AiServiceCompletedEvent event) {
        System.out.println("Any AI service completed");
    }

    // Observe all errors
    public void onAnyError(@Observes AiServiceErrorEvent event) {
        logError(event);
    }

    private void logError(AiServiceErrorEvent event) {
        // Error logging logic
    }
}

Custom Metrics Collection

import io.quarkiverse.langchain4j.observability.AiServiceSelector;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Observes;
import jakarta.inject.Inject;
import java.util.concurrent.ConcurrentHashMap;

@ApplicationScoped
public class MetricsCollector {

    @Inject
    MeterRegistry registry;

    private final ConcurrentHashMap<String, Long> startTimes = new ConcurrentHashMap<>();

    public void onStarted(
        @Observes @AiServiceSelector(MyAssistant.class) AiServiceStartedEvent event
    ) {
        String key = event.methodName() + "-" + System.identityHashCode(event);
        startTimes.put(key, System.nanoTime());
    }

    public void onCompleted(
        @Observes @AiServiceSelector(MyAssistant.class) AiServiceCompletedEvent event
    ) {
        String key = event.methodName() + "-" + System.identityHashCode(event);
        Long startTime = startTimes.remove(key);

        if (startTime != null) {
            long duration = System.nanoTime() - startTime;
            Timer.builder("ai.service.duration")
                .tag("method", event.methodName())
                .tag("service", "MyAssistant")
                .register(registry)
                .record(duration, java.util.concurrent.TimeUnit.NANOSECONDS);
        }
    }

    public void onError(
        @Observes @AiServiceSelector(MyAssistant.class) AiServiceErrorEvent event
    ) {
        registry.counter("ai.service.errors",
            "method", event.methodName(),
            "service", "MyAssistant"
        ).increment();
    }
}

Event Types

ToolInputGuardrailExecutedEvent

Event fired when tool input guardrail executes.

// Package: io.quarkiverse.langchain4j.runtime.observability
/**
 * Event fired when tool input guardrail is executed.
 * Package: io.quarkiverse.langchain4j.runtime.observability
 */
public record ToolInputGuardrailExecutedEvent(
    ToolInvocationContext toolInvocationContext,
    Class<?> toolClass,
    String toolName,
    ToolGuardrailOutcome outcome,
    long duration
) {}

ToolOutputGuardrailExecutedEvent

Event fired when tool output guardrail executes.

// Package: io.quarkiverse.langchain4j.runtime.observability
/**
 * Event fired when tool output guardrail is executed.
 * Package: io.quarkiverse.langchain4j.runtime.observability
 */
public record ToolOutputGuardrailExecutedEvent(
    ToolInvocationContext toolInvocationContext,
    Class<?> toolClass,
    String toolName,
    ToolGuardrailOutcome outcome,
    long duration
) {}

Supporting Types

AiServiceListenerAdapter

Adapter for creating AI service listeners.

// Package: io.quarkiverse.langchain4j.observability
/**
 * Adapter for creating AI service event listeners.
 * Implements LangChain4j AiServiceListener and fires CDI events.
 *
 * @param <T> Event type
 */
public record AiServiceListenerAdapter<T extends AiServiceEvent>(
    Class<T> eventClass,
    Class<?> aiServiceClass
) implements AiServiceListener<T> {

    /**
     * Handle AI service event by firing CDI event.
     *
     * @param event The AI service event
     */
    @Override
    public void onEvent(T event);
}

AiServiceSelectorLiteral

Literal for programmatic @AiServiceSelector creation.

// Package: io.quarkiverse.langchain4j.observability
/**
 * AnnotationLiteral for programmatic @AiServiceSelector creation.
 */
public class AiServiceSelectorLiteral
    extends AnnotationLiteral<AiServiceSelector>
    implements AiServiceSelector {

    /**
     * Create literal for AI service class.
     *
     * @param aiServiceClass The AI service class
     * @return AiServiceSelector literal
     */
    public static AiServiceSelectorLiteral of(Class<?> aiServiceClass);

    @Override
    public Class<?> value();
}

GuardrailOutcome Enum

// Package: io.quarkiverse.langchain4j.runtime.observability
/**
 * Enum representing guardrail validation outcomes.
 */
public enum GuardrailOutcome {
    SUCCESS,
    FAILURE,
    FATAL
}

ToolGuardrailOutcome Enum

// Package: io.quarkiverse.langchain4j.runtime.observability
/**
 * Enum representing tool-specific guardrail outcomes.
 */
public enum ToolGuardrailOutcome {
    SUCCESS,
    FAILURE,
    FATAL
}

Built-in Observability

Quarkus LangChain4j Core provides built-in observability features:

Metrics Collection

Automatic metrics when quarkus-micrometer is present:

# Enable metrics
quarkus.langchain4j.metrics.enabled=true

Metrics collected:

langchain4j.aiservice.duration - AI service method duration
langchain4j.aiservice.requests - Number of requests
langchain4j.aiservice.errors - Number of errors
langchain4j.tool.executions - Tool execution count
langchain4j.guardrail.executions - Guardrail execution count

OpenTelemetry Tracing

Automatic tracing when quarkus-opentelemetry is present:

# Configure tracing
quarkus.langchain4j.tracing.include-prompt=true
quarkus.langchain4j.tracing.include-completion=true
quarkus.langchain4j.tracing.include-tool-arguments=true
quarkus.langchain4j.tracing.include-tool-result=true

Spans created:

AI service method invocation
Chat model calls
Tool executions
Guardrail validations

Use Cases

Observability is useful for:

Performance Monitoring: Track response times and latencies
Error Tracking: Monitor and alert on errors
Usage Analytics: Understand how AI services are used
Debugging: Trace execution flow through tools and guardrails
Cost Tracking: Monitor token usage and costs
Compliance: Audit tool executions and guardrail outcomes
A/B Testing: Compare metrics between different configurations
SLA Monitoring: Ensure service meets performance requirements

Version

tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-core

observability.mddocs/reference/

Observability & Events

Capabilities

@AiServiceSelector Annotation

AiServiceEvents Enum

Event Observation

Observing All Events from an AI Service

Observing Events from All AI Services

Custom Metrics Collection

Event Types

ToolInputGuardrailExecutedEvent

ToolOutputGuardrailExecutedEvent

Supporting Types

AiServiceListenerAdapter

AiServiceSelectorLiteral

GuardrailOutcome Enum

ToolGuardrailOutcome Enum

Built-in Observability

Metrics Collection

OpenTelemetry Tracing

Use Cases

Version

tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-core

observability.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/reference/

Observability & Events

Capabilities

@AiServiceSelector Annotation

AiServiceEvents Enum

Event Observation

Observing All Events from an AI Service

Observing Events from All AI Services

Custom Metrics Collection

Event Types

ToolInputGuardrailExecutedEvent

ToolOutputGuardrailExecutedEvent

Supporting Types

AiServiceListenerAdapter

AiServiceSelectorLiteral

GuardrailOutcome Enum

ToolGuardrailOutcome Enum

Built-in Observability

Metrics Collection

OpenTelemetry Tracing

Use Cases

observability.mddocs/reference/