This repository contains an auto-generated Langfuse API client for Java based on our API specification. See the Langfuse API reference for more details on the available endpoints.

Note: We recommend to solve tracing via the OpenTelemetry Instrumentation instead of using the Ingestion API directly. You can use the OpenTelemetry Java SDK and export spans to the Langfuse OTel endpoint. This allows for a more detailed and standardized tracing experience without the need to handle batching and updates internally. Check out our Spring AI Example for more details.

The recommended way to install the langfuse-java API client is via Maven Central:

<dependency>
    <groupId>com.langfuse</groupId>
    <artifactId>langfuse-java</artifactId>
    <version>0.2.0</version>
</dependency>

Instantiate the Langfuse Client with the respective endpoint and your API Keys.

import com.langfuse.client.LangfuseClient;

LangfuseClient client = LangfuseClient.builder()
        .url("https://cloud.langfuse.com") // 🇪🇺 EU data region
        // .url("https://us.cloud.langfuse.com") // 🇺🇸 US data region
        // .url("http://localhost:3000") // 🏠 Local deployment
        .credentials("pk-lf-...", "sk-lf-...")
        .build();

An async client is also available via AsyncLangfuseClient.builder() with the same configuration options.

Make requests using the clients:

import com.langfuse.client.core.LangfuseClientApiException;
import com.langfuse.client.resources.prompts.types.PromptMetaListResponse;

try {
    PromptMetaListResponse prompts = client.prompts().list();
} catch (LangfuseClientApiException error) {
    System.out.println(error.body());
    System.out.println(error.statusCode());
}

Unit tests (deserialization, query string mapping) run without any credentials:

mvn test

Integration tests connect to a real Langfuse project. They require credentials and are excluded from mvn test.

1. Copy .env.example to .env and fill in your API keys:

   cp .env.example .env

2. Ensure your Langfuse project contains the following prompts:

   • test-chat-prompt — chat type, at least one message with role and content
   • test-text-prompt — text type, non-empty prompt text

3. Run all tests (unit + integration):

   mvn verify

   Or run only integration tests:

   mvn failsafe:integration-test

Integration tests skip gracefully when credentials are absent.

Run ./mvnw release:prepare -DreleaseVersion= with the version you want to create. Push the changes including the tag.

This project is configured to publish to Maven Central. To publish to Maven Central, you need to configure the following secrets in your GitHub repository:

• OSSRH_USERNAME: Your Sonatype OSSRH username
• OSSRH_PASSWORD: Your Sonatype OSSRH password
• GPG_PRIVATE_KEY: Your GPG private key for signing artifacts
• GPG_PASSPHRASE: The passphrase for your GPG private key

1. Ensure that langfuse-java is placed in the same directory as the main langfuse repository.
2. Setup a new Java fern generator using

      - name: fernapi/fern-java-sdk
        version: 3.38.1
        output:
          location: local-file-system
          path: ../../../../langfuse-java/src/main/java/com/langfuse/client/
        config:
          client-class-name: LangfuseClient

3. Generate the new client code using npx fern-api generate --api server.
4. Manually set the package across all files to com.langfuse.client.
5. Verify that LangfuseClientBuilder.setAuthentication() uses Basic auth (not Bearer).
6. Adjust Javadoc strings with HTML properties as the apidocs package does not support them.
7. Commit the changes in langfuse-java and push them to the repository.