CtrlK
BlogDocsLog inGet started
Tessl Logo

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

sessions.mddocs/

Sessions

The Sessions API provides retrieval of sessions and their associated traces. Sessions group related traces together, typically representing a conversation or workflow that spans multiple interactions.

Capabilities

SessionsClient

Client for retrieving sessions and their traces.

/**
 * List sessions with filters and pagination
 *
 * @param request Optional filters (date range, environment, pagination)
 * @param requestOptions Optional request configuration
 */
PaginatedSessions list();
PaginatedSessions list(GetSessionsRequest request);
PaginatedSessions list(GetSessionsRequest request, RequestOptions requestOptions);

/**
 * Get a session with all its traces
 * Note: Traces on this endpoint are not paginated
 *
 * @param sessionId Session ID
 * @param requestOptions Optional request configuration
 */
SessionWithTraces get(String sessionId);
SessionWithTraces get(String sessionId, RequestOptions requestOptions);

Usage Examples:

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.sessions.requests.GetSessionsRequest;
import com.langfuse.client.resources.sessions.types.PaginatedSessions;
import com.langfuse.client.resources.commons.types.*;

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

// List all sessions
PaginatedSessions sessions = client.sessions().list();
for (Session session : sessions.getData()) {
    System.out.println("Session: " + session.getId());
    System.out.println("  Created: " + session.getCreatedAt());
    System.out.println("  Environment: " + session.getEnvironment().orElse("none"));
}

// Filter by date range
GetSessionsRequest request = GetSessionsRequest.builder()
    .fromTimestamp(OffsetDateTime.parse("2025-10-01T00:00:00Z"))
    .toTimestamp(OffsetDateTime.parse("2025-10-14T23:59:59Z"))
    .limit(50)
    .build();

PaginatedSessions recentSessions = client.sessions().list(request);

// Filter by environment
GetSessionsRequest prodRequest = GetSessionsRequest.builder()
    .environment("production")
    .build();

PaginatedSessions prodSessions = client.sessions().list(prodRequest);

// Get a specific session with all traces
SessionWithTraces session = client.sessions().get("session-123");
System.out.println("Session: " + session.getId());
System.out.println("Traces: " + session.getTraces().size());

for (Trace trace : session.getTraces()) {
    System.out.println("  - " + trace.getName().orElse("unnamed"));
    System.out.println("    Timestamp: " + trace.getTimestamp());
}

Request Types

GetSessionsRequest

import java.time.OffsetDateTime;

/**
 * Request parameters for listing sessions
 */
public final class GetSessionsRequest {
    Optional<Integer> getPage();                  // Page number (default: 1)
    Optional<Integer> getLimit();                 // Items per page (default: 50)
    Optional<OffsetDateTime> getFromTimestamp();  // Filter from this datetime
    Optional<OffsetDateTime> getToTimestamp();    // Filter until this datetime
    Optional<String> getEnvironment();            // Filter by environment

    static Builder builder();
}

Response Types

Session

import java.time.OffsetDateTime;

/**
 * Session object
 */
public final class Session {
    String getId();                     // Session ID
    OffsetDateTime getCreatedAt();      // Creation timestamp
    String getProjectId();              // Project ID
    Optional<String> getEnvironment();  // Environment

    static Builder builder();
}

PaginatedSessions

/**
 * Paginated list of sessions
 */
public final class PaginatedSessions {
    List<Session> getData();
    MetaResponse getMeta();  // Pagination metadata

    static Builder builder();
}

SessionWithTraces

import java.time.OffsetDateTime;

/**
 * Session with all its traces
 * Note: Traces are not paginated
 */
public final class SessionWithTraces {
    String getId();
    OffsetDateTime getCreatedAt();      // Creation timestamp
    String getProjectId();              // Project ID
    Optional<String> getEnvironment();  // Environment
    List<Trace> getTraces();            // All traces in session

    static Builder builder();
}

Complete Session Analysis Example

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.sessions.requests.GetSessionsRequest;
import com.langfuse.client.resources.sessions.types.PaginatedSessions;
import com.langfuse.client.resources.commons.types.*;
import java.time.OffsetDateTime;
import java.util.Map;
import java.util.HashMap;

public class SessionAnalysisExample {
    public static void main(String[] args) {
        LangfuseClient client = LangfuseClient.builder()
            .url("https://cloud.langfuse.com")
            .credentials("pk-lf-...", "sk-lf-...")
            .build();

        // 1. List recent sessions
        GetSessionsRequest request = GetSessionsRequest.builder()
            .fromTimestamp(OffsetDateTime.parse("2025-10-14T00:00:00Z"))
            .environment("production")
            .limit(20)
            .build();

        PaginatedSessions sessions = client.sessions().list(request);

        System.out.println("Found " + sessions.getMeta().getTotalItems() + " sessions");

        // 2. Analyze each session
        for (Session session : sessions.getData()) {
            System.out.println("\nSession: " + session.getId());
            System.out.println("  Created: " + session.getCreatedAt());
            System.out.println("  Environment: " + session.getEnvironment().orElse("none"));

            // Get detailed session data
            SessionWithTraces fullSession = client.sessions().get(session.getId());

            // Analyze traces in session
            System.out.println("  Trace count: " + fullSession.getTraces().size());
            for (Trace trace : fullSession.getTraces()) {
                System.out.println("    - " + trace.getName().orElse("unnamed"));
                System.out.println("      Time: " + trace.getTimestamp());
            }

            // Calculate session metrics
            long durationMs = 0;
            if (!fullSession.getTraces().isEmpty()) {
                // Calculate session duration from first to last trace
                String firstTime = fullSession.getTraces().get(0).getTimestamp();
                String lastTime = fullSession.getTraces()
                    .get(fullSession.getTraces().size() - 1).getTimestamp();

                System.out.println("      First trace: " + firstTime);
                System.out.println("      Last trace: " + lastTime);
            }
        }

        // 3. Group by environment
        Map<String, Integer> envCount = new HashMap<>();
        for (Session session : sessions.getData()) {
            String env = session.getEnvironment().orElse("unknown");
            envCount.merge(env, 1, Integer::sum);
        }

        System.out.println("\nSessions by environment:");
        envCount.forEach((env, count) -> {
            System.out.println("  " + env + ": " + count + " sessions");
        });
    }
}

Query Patterns

Finding Sessions by Time Range

import java.time.OffsetDateTime;

GetSessionsRequest timeRangeRequest = GetSessionsRequest.builder()
    .fromTimestamp(OffsetDateTime.parse("2025-10-01T00:00:00Z"))
    .toTimestamp(OffsetDateTime.parse("2025-10-31T23:59:59Z"))
    .build();

PaginatedSessions monthlySessions = client.sessions().list(timeRangeRequest);

Paginating Through Sessions

int page = 1;
boolean hasMore = true;

while (hasMore) {
    GetSessionsRequest pageRequest = GetSessionsRequest.builder()
        .page(page)
        .limit(100)
        .build();

    PaginatedSessions sessions = client.sessions().list(pageRequest);

    // Process sessions
    for (Session session : sessions.getData()) {
        System.out.println("Session: " + session.getId());
    }

    // Check if more pages exist
    hasMore = page < sessions.getMeta().getTotalPages();
    page++;
}

Filtering by Environment

GetSessionsRequest prodRequest = GetSessionsRequest.builder()
    .environment("production")
    .limit(50)
    .build();

PaginatedSessions prodSessions = client.sessions().list(prodRequest);

Best Practices

  1. Use Session IDs: Group related traces with a consistent sessionId
  2. Track Conversations: Use sessions to represent multi-turn conversations
  3. Environment Separation: Filter by environment to separate prod/dev data
  4. Pagination: Use pagination for large result sets
  5. Time-Based Queries: Filter by date range for performance
  6. Analyze Trace Details: Use SessionWithTraces to get full trace information
  7. Monitor Creation Timestamps: Track session creation times for temporal analysis

Use Cases

Conversation Analysis

Sessions are ideal for analyzing multi-turn conversations:

SessionWithTraces chatSession = client.sessions().get("session-123");

System.out.println("Session: " + chatSession.getId());
System.out.println("Number of traces: " + chatSession.getTraces().size());
System.out.println("Environment: " + chatSession.getEnvironment().orElse("none"));

for (int i = 0; i < chatSession.getTraces().size(); i++) {
    Trace turn = chatSession.getTraces().get(i);
    System.out.println("Trace " + (i + 1) + ": " + turn.getName().orElse(""));
}

Environment-based Analysis

Analyze sessions by environment:

import java.time.OffsetDateTime;

GetSessionsRequest request = GetSessionsRequest.builder()
    .fromTimestamp(OffsetDateTime.parse("2025-10-01T00:00:00Z"))
    .environment("production")
    .build();

PaginatedSessions sessions = client.sessions().list(request);

System.out.println("Production sessions: " + sessions.getMeta().getTotalItems());

Trace Analysis within Sessions

Analyze traces within a session:

SessionWithTraces session = client.sessions().get("session-123");

System.out.println("Session: " + session.getId());
System.out.println("Total traces: " + session.getTraces().size());

// Analyze each trace
for (Trace trace : session.getTraces()) {
    System.out.println("Trace: " + trace.getId());
    System.out.println("  Name: " + trace.getName().orElse("unnamed"));
    System.out.println("  Timestamp: " + trace.getTimestamp());
}

Related Documentation

  • Traces and Observations - Traces within sessions
  • Ingestion API - Creating traces with session IDs
  • Common Types - Session type definitions
  • Pagination - Pagination utilities

Install with Tessl CLI

npx tessl i tessl/maven-com-langfuse--langfuse-java

docs

client-configuration.md

comments-annotations.md

common-types.md

datasets.md

exceptions.md

health.md

index.md

ingestion.md

media.md

metrics.md

models.md

pagination.md

projects-organizations.md

prompts.md

scim.md

scores.md

sessions.md

traces-observations.md

tile.json