Langfuse.Session (Langfuse v0.2.0)

View Source

Group related traces into sessions.

Sessions represent user conversations or interaction sequences. Traces with the same session ID are grouped together in the Langfuse dashboard, enabling analysis of multi-turn interactions.

Creating Sessions

Generate a session ID and use it across related traces:

session_id = Langfuse.Session.new_id()

trace1 = Langfuse.trace(name: "turn-1", session_id: session_id)
trace2 = Langfuse.trace(name: "turn-2", session_id: session_id)

Or create a session struct for local metadata:

session = Langfuse.Session.start(metadata: %{user_agent: "mobile"})

trace = Langfuse.trace(name: "request", session_id: session.id)

Scoring Sessions

Evaluate entire sessions with aggregate scores:

Langfuse.Session.score(session_id,
  name: "satisfaction",
  value: 4.5,
  comment: "User completed goal"
)

Session IDs

Session IDs are strings prefixed with "session_" followed by 24 hex characters. You can also use custom session IDs if preferred.

Summary

Types

session_id()

A unique session identifier string.

t()

A session struct for local session management.

Functions

get_id(id)

Returns the session ID from a session struct or string.

new_id()

Generates a new unique session ID.

score(session, opts)

Attaches a score to a session.

start(opts \\ [])

Creates a new session struct.

Types

session_id()

@type session_id() :: String.t()

A unique session identifier string.

t()

@type t() :: %Langfuse.Session{
  created_at: DateTime.t(),
  id: session_id(),
  metadata: map() | nil
}

A session struct for local session management.

The struct holds the session ID and optional metadata. The :created_at timestamp is set automatically when the session is started.

Functions

get_id(id)

@spec get_id(t() | session_id()) :: session_id()

Returns the session ID from a session struct or string.

Accepts either a Langfuse.Session struct or a session ID string, returning the ID in either case.

Examples

iex> session = Langfuse.Session.start(id: "sess-123")
iex> Langfuse.Session.get_id(session)
"sess-123"

iex> Langfuse.Session.get_id("sess-456")
"sess-456"

new_id()

@spec new_id() :: session_id()

Generates a new unique session ID.

Examples

iex> session_id = Langfuse.Session.new_id()
iex> String.starts_with?(session_id, "session_")
true

score(session, opts)

@spec score(
  t() | session_id(),
  keyword()
) :: :ok | {:error, term()}

Attaches a score to a session.

Session scores evaluate the entire session rather than individual traces or observations within it.

Options

  • :name - Score name (required).
  • :value - Numeric value for numeric or boolean scores.
  • :string_value - String value for categorical scores.
  • :data_type - Score type: :numeric, :categorical, or :boolean. Auto-inferred if not provided.
  • :comment - Free-text comment or reasoning.
  • :id - Custom score ID for idempotent updates.
  • :config_id - Reference to a score configuration.

Examples

iex> Langfuse.Session.score("session-123", name: "satisfaction", value: 4.5)
:ok

iex> session = Langfuse.Session.start()
iex> Langfuse.Session.score(session,
...>   name: "outcome",
...>   string_value: "converted",
...>   data_type: :categorical
...> )
:ok

start(opts \\ [])

@spec start(keyword()) :: t()

Creates a new session struct.

The session struct is a local convenience for managing session metadata. It is not sent to Langfuse; only the session ID is used when creating traces.

Options

  • :id - Custom session ID. Auto-generated with new_id/0 if not provided.
  • :metadata - Local metadata map for application use.

Examples

iex> session = Langfuse.Session.start()
iex> String.starts_with?(session.id, "session_")
true

iex> session = Langfuse.Session.start(id: "custom-session")
iex> session.id
"custom-session"

iex> session = Langfuse.Session.start(metadata: %{source: "api"})
iex> session.metadata
%{source: "api"}