tessl/maven-com-langfuse--langfuse-java

Java client for the Langfuse API providing access to observability and analytics features for LLM applications

Overview

Eval results

Files

Client Configuration

Name: tessl/maven-com-langfuse--langfuse-java
Author: tessl

The Langfuse Java client provides flexible configuration options through a builder pattern, allowing customization of API endpoints, authentication, headers, timeouts, and HTTP client settings.

Capabilities

LangfuseClient

The main entry point for the Langfuse API client. Provides access to all resource-specific clients.

/**
 * Main Langfuse API client
 * Provides access to all resource clients
 */
public class LangfuseClient {
    // Resource client accessors
    AnnotationQueuesClient annotationQueues();
    CommentsClient comments();
    DatasetItemsClient datasetItems();
    DatasetRunItemsClient datasetRunItems();
    DatasetsClient datasets();
    HealthClient health();
    IngestionClient ingestion();
    MediaClient media();
    MetricsClient metrics();
    ModelsClient models();
    ObservationsClient observations();
    OrganizationsClient organizations();
    ProjectsClient projects();
    PromptVersionClient promptVersion();
    PromptsClient prompts();
    ScimClient scim();
    ScoreConfigsClient scoreConfigs();
    ScoreV2Client scoreV2();
    ScoreClient score();
    SessionsClient sessions();
    TraceClient trace();

    // Builder factory
    static LangfuseClientBuilder builder();
}

Usage Example:

import com.langfuse.client.LangfuseClient;

// Create client
LangfuseClient client = LangfuseClient.builder()
    .url("https://cloud.langfuse.com")
    .credentials("pk-lf-...", "sk-lf-...")
    .build();

// Access resource clients
var prompts = client.prompts().list();
var traces = client.trace().list();
var health = client.health().health();

LangfuseClientBuilder

Builder for creating and configuring LangfuseClient instances.

/**
 * Builder for LangfuseClient with configuration options
 */
public class LangfuseClientBuilder {
    /**
     * Set authentication credentials (Basic Auth)
     * @param username Public key (pk-lf-...)
     * @param password Secret key (sk-lf-...)
     */
    LangfuseClientBuilder credentials(String username, String password);

    /**
     * Set custom API URL
     * @param url Base URL for Langfuse API
     *            - https://cloud.langfuse.com (EU)
     *            - https://us.cloud.langfuse.com (US)
     *            - http://localhost:3000 (local)
     */
    LangfuseClientBuilder url(String url);

    /**
     * Set X-Langfuse-Sdk-Name header
     * @param xLangfuseSdkName SDK name identifier
     */
    LangfuseClientBuilder xLangfuseSdkName(String xLangfuseSdkName);

    /**
     * Set X-Langfuse-Sdk-Version header
     * @param xLangfuseSdkVersion SDK version identifier
     */
    LangfuseClientBuilder xLangfuseSdkVersion(String xLangfuseSdkVersion);

    /**
     * Set X-Langfuse-Public-Key header
     * @param xLangfusePublicKey Public key for identification
     */
    LangfuseClientBuilder xLangfusePublicKey(String xLangfusePublicKey);

    /**
     * Set request timeout
     * @param timeout Timeout in seconds (default: 60)
     */
    LangfuseClientBuilder timeout(int timeout);

    /**
     * Set custom OkHttpClient
     * @param httpClient Configured OkHttpClient instance
     */
    LangfuseClientBuilder httpClient(OkHttpClient httpClient);

    /**
     * Build the configured LangfuseClient
     */
    LangfuseClient build();
}

Usage Examples:

import com.langfuse.client.LangfuseClient;
import okhttp3.OkHttpClient;
import java.util.concurrent.TimeUnit;

// Basic configuration
LangfuseClient client = LangfuseClient.builder()
    .url("https://cloud.langfuse.com")
    .credentials("pk-lf-...", "sk-lf-...")
    .build();

// With custom timeout
LangfuseClient client = LangfuseClient.builder()
    .url("https://us.cloud.langfuse.com")
    .credentials("pk-lf-...", "sk-lf-...")
    .timeout(120)  // 2 minutes
    .build();

// With custom headers
LangfuseClient client = LangfuseClient.builder()
    .url("https://cloud.langfuse.com")
    .credentials("pk-lf-...", "sk-lf-...")
    .xLangfuseSdkName("my-app")
    .xLangfuseSdkVersion("1.0.0")
    .xLangfusePublicKey("pk-lf-...")
    .build();

// With custom HTTP client
OkHttpClient customHttpClient = new OkHttpClient.Builder()
    .connectTimeout(30, TimeUnit.SECONDS)
    .readTimeout(60, TimeUnit.SECONDS)
    .build();

LangfuseClient client = LangfuseClient.builder()
    .url("https://cloud.langfuse.com")
    .credentials("pk-lf-...", "sk-lf-...")
    .httpClient(customHttpClient)
    .build();

ClientOptions

Encapsulates client-level configuration including environment, headers, and HTTP client settings.

/**
 * Client-level configuration options
 */
public class ClientOptions {
    /**
     * Get the configured environment
     */
    Environment environment();

    /**
     * Get headers with optional request-specific overrides
     * @param requestOptions Per-request overrides (optional)
     */
    Map<String, String> headers(RequestOptions requestOptions);

    /**
     * Get the configured HTTP client
     */
    OkHttpClient httpClient();

    /**
     * Get HTTP client with custom timeout from request options
     * @param requestOptions Per-request overrides (optional)
     */
    OkHttpClient httpClientWithTimeout(RequestOptions requestOptions);

    /**
     * Create a new builder
     */
    static Builder builder();
}

ClientOptions.Builder:

/**
 * Builder for ClientOptions
 */
public static class Builder {
    /**
     * Set the API environment
     * @param environment Environment with base URL
     */
    Builder environment(Environment environment);

    /**
     * Add a static header
     * @param key Header name
     * @param value Header value
     */
    Builder addHeader(String key, String value);

    /**
     * Add a dynamic header (computed at request time)
     * @param key Header name
     * @param value Supplier for header value
     */
    Builder addHeader(String key, Supplier<String> value);

    /**
     * Set timeout in seconds
     * @param timeout Timeout value (default: 60)
     */
    Builder timeout(int timeout);

    /**
     * Set custom HTTP client
     * @param httpClient Configured OkHttpClient
     */
    Builder httpClient(OkHttpClient httpClient);

    /**
     * Build the ClientOptions
     */
    ClientOptions build();
}

Usage Example:

import com.langfuse.client.core.ClientOptions;
import com.langfuse.client.core.Environment;

ClientOptions options = ClientOptions.builder()
    .environment(Environment.custom("https://cloud.langfuse.com"))
    .addHeader("X-Custom-Header", "value")
    .addHeader("X-Dynamic-Header", () -> String.valueOf(System.currentTimeMillis()))
    .timeout(90)
    .build();

RequestOptions

Per-request configuration for overriding client-level settings.

/**
 * Per-request configuration options
 */
public class RequestOptions {
    /**
     * Get optional timeout value
     */
    Optional<Integer> getTimeout();

    /**
     * Get timeout time unit
     */
    TimeUnit getTimeoutTimeUnit();

    /**
     * Get request-specific headers
     */
    Map<String, String> getHeaders();

    /**
     * Create a new builder
     */
    static Builder builder();
}

RequestOptions.Builder:

/**
 * Builder for RequestOptions
 */
public static class Builder {
    /**
     * Set X-Langfuse-Sdk-Name header
     */
    Builder xLangfuseSdkName(String xLangfuseSdkName);

    /**
     * Set X-Langfuse-Sdk-Version header
     */
    Builder xLangfuseSdkVersion(String xLangfuseSdkVersion);

    /**
     * Set X-Langfuse-Public-Key header
     */
    Builder xLangfusePublicKey(String xLangfusePublicKey);

    /**
     * Set timeout value (milliseconds by default)
     * @param timeout Timeout value
     */
    Builder timeout(Integer timeout);

    /**
     * Set timeout with custom time unit
     * @param timeout Timeout value
     * @param timeoutTimeUnit Time unit for timeout
     */
    Builder timeout(Integer timeout, TimeUnit timeoutTimeUnit);

    /**
     * Add a static header
     * @param key Header name
     * @param value Header value
     */
    Builder addHeader(String key, String value);

    /**
     * Add a dynamic header
     * @param key Header name
     * @param value Supplier for header value
     */
    Builder addHeader(String key, Supplier<String> value);

    /**
     * Build the RequestOptions
     */
    RequestOptions build();
}

Usage Example:

import com.langfuse.client.core.RequestOptions;
import java.util.concurrent.TimeUnit;

// Override timeout for a single request
RequestOptions options = RequestOptions.builder()
    .timeout(5, TimeUnit.MINUTES)
    .build();

var prompts = client.prompts().list(request, options);

// Add custom headers for a single request
RequestOptions options = RequestOptions.builder()
    .addHeader("X-Request-ID", "unique-request-id")
    .xLangfusePublicKey("pk-lf-...")
    .build();

var trace = client.trace().get(traceId, options);

Environment

Represents the API environment and base URL.

/**
 * API environment configuration
 */
public class Environment {
    /**
     * Get the base URL
     */
    String getUrl();

    /**
     * Create a custom environment with specified URL
     * @param url Base URL for API
     */
    static Environment custom(String url);
}

Usage Example:

import com.langfuse.client.core.Environment;

// Create custom environment
Environment euEnv = Environment.custom("https://cloud.langfuse.com");
Environment usEnv = Environment.custom("https://us.cloud.langfuse.com");
Environment localEnv = Environment.custom("http://localhost:3000");

Configuration Patterns

Environment-Specific Clients

// EU Region
LangfuseClient euClient = LangfuseClient.builder()
    .url("https://cloud.langfuse.com")
    .credentials("pk-lf-...", "sk-lf-...")
    .build();

// US Region
LangfuseClient usClient = LangfuseClient.builder()
    .url("https://us.cloud.langfuse.com")
    .credentials("pk-lf-...", "sk-lf-...")
    .build();

// Local Development
LangfuseClient localClient = LangfuseClient.builder()
    .url("http://localhost:3000")
    .credentials("pk-lf-...", "sk-lf-...")
    .build();

Per-Request Customization

// Client with default 60s timeout
LangfuseClient client = LangfuseClient.builder()
    .url("https://cloud.langfuse.com")
    .credentials("pk-lf-...", "sk-lf-...")
    .build();

// Override timeout for specific long-running request
RequestOptions longTimeout = RequestOptions.builder()
    .timeout(5, TimeUnit.MINUTES)
    .build();

var result = client.ingestion().batch(largeRequest, longTimeout);

// Add custom tracking headers
RequestOptions trackingOptions = RequestOptions.builder()
    .addHeader("X-Request-ID", requestId)
    .addHeader("X-User-ID", userId)
    .build();

var trace = client.trace().get(traceId, trackingOptions);

Custom HTTP Client Configuration

import okhttp3.OkHttpClient;
import okhttp3.logging.HttpLoggingInterceptor;
import java.util.concurrent.TimeUnit;

// Configure HTTP client with logging and custom timeouts
HttpLoggingInterceptor logging = new HttpLoggingInterceptor();
logging.setLevel(HttpLoggingInterceptor.Level.BODY);

OkHttpClient httpClient = new OkHttpClient.Builder()
    .connectTimeout(30, TimeUnit.SECONDS)
    .readTimeout(90, TimeUnit.SECONDS)
    .writeTimeout(90, TimeUnit.SECONDS)
    .addInterceptor(logging)
    .build();

LangfuseClient client = LangfuseClient.builder()
    .url("https://cloud.langfuse.com")
    .credentials("pk-lf-...", "sk-lf-...")
    .httpClient(httpClient)
    .build();

Authentication

The client uses HTTP Basic Authentication with your Langfuse API credentials:

Username: Public key (format: pk-lf-...)
Password: Secret key (format: sk-lf-...)

LangfuseClient client = LangfuseClient.builder()
    .url("https://cloud.langfuse.com")
    .credentials("pk-lf-1234567890abcdef", "sk-lf-fedcba0987654321")
    .build();

Some operations require an organization-scoped API key:

Project creation and deletion
API key management
Organization and project membership management
SCIM user provisioning

tessl/maven-com-langfuse--langfuse-java