Integrating Langfuse with Quarkus LangChain4j

This guide shows how to integrate Langfuse with Quarkus LangChain4j using the Quarkus Langfuse extension.

• Quarkus LangChain4j: A Quarkus based integration of LangChain4j for AI development with built-in OTel tracing for AI calls.
• Quarkus Langfuse: A Quarkus based integration of Langfuse providing seamless integrations between LangChain4j, Langfuse, and OpenTelemetry.
• Langfuse: Open source AI engineering platform for observability, evals and prompt management.

Step 1: Add Dependencies

Add the quarkus-opentelemetry and quarkus-langfuse dependencies to your pom.xml (Gradle users can include equivalent coordinates in Gradle):

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-opentelemetry</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkiverse.langfuse</groupId>
    <artifactId>quarkus-langfuse</artifactId>
</dependency>

Step 2: Configure Langfuse Connection

Sign up for Langfuse Cloud or self-host Langfuse, then configure the connection in application.properties:

quarkus.langfuse.base-url=https://cloud.langfuse.com
quarkus.langfuse.username=<your public key>
quarkus.langfuse.password=<your secret key>

That’s it. The quarkus-langfuse extension automatically configures:

• The OTLP trace exporter endpoint (derived from base-url)
• Authorization headers (Basic auth from username/password)
• Span filtering — by default only gen_ai spans and their ancestors are exported (AI_ONLY mode)
• Prompt and completion tracing (include-prompt, include-completion, include-tool-arguments, include-tool-result all set to true)
• Automatically set Langfuse’s specific input and output span attributes for better trace visualization in Langfuse
• Dual exporting to both a standard LGTM stack AND langfuse

Step 3: Run a Test AI Operation

Start your Quarkus application. Trigger an AI operation that Quarkus LangChain4j handles — for example, call a service or controller that uses a ChatModel to generate a completion.

Note: A complete example is available on GitHub.

@RegisterAiService(tools = EmailService.class)
public interface MyAiService {

    /**
     * Ask the LLM to create a poem about the given topic.
     *
     * @param topic the topic of the poem
     * @param lines the number of line of the poem
     * @return the poem
     */
    @SystemMessage("You are a professional poet")
    @UserMessage("""
            Write a single poem about {topic}. The poem should be {lines} lines long and your response should only include the poem itself, nothing else.
            Then send this poem by email. Your response should include the poem.
            """)
    String writeAPoem(String topic, int lines);

}

@Singleton
public class Startup {

    public void writeAPoem(@Observes StartupEvent event, MyAiService service) {
        System.out.println(service.writeAPoem("Langfuse", 4));
    }
}

Troubleshooting

No Traces:

• Check the logs of the application for potential clues
• Check the Troubleshooting page

Manual Configuration (without quarkus-langfuse)

If you prefer not to use the quarkus-langfuse extension, you can configure the OpenTelemetry exporter manually to point to Langfuse’s OTLP endpoint:

quarkus.otel.exporter.otlp.traces.protocol=http/protobuf
quarkus.otel.exporter.otlp.endpoint=https://cloud.langfuse.com/api/public/otel
quarkus.otel.exporter.otlp.headers=Authorization=Basic <base64 of public_key:secret_key>,x-langfuse-ingestion-version=4

The ingestion version header enables real-time ingestion in Langfuse v4.

You will also need to manually enable prompt 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

See the Langfuse OpenTelemetry documentation for more details on authentication and manual setup.