Langfuse.Trace (Langfuse v0.1.0)

View Source

A trace represents a single request or operation in an LLM application.

Traces are the top-level containers for observability data. They group related observations (spans, generations, events) into a logical unit that can be analyzed, scored, and debugged in the Langfuse dashboard.

Creating Traces

Use new/1 to create a trace at the start of an operation:

trace = Langfuse.Trace.new(name: "chat-completion")

Or with additional context:

trace = Langfuse.Trace.new(
  name: "rag-pipeline",
  user_id: "user-123",
  session_id: "session-abc",
  tags: ["production"],
  metadata: %{environment: "prod"}
)

Updating Traces

Use update/2 to add output or modify trace data after creation:

trace = Langfuse.Trace.update(trace,
  output: %{response: "Hello!"},
  metadata: %{tokens_used: 150}
)

Linking to Sessions

Traces with the same session_id are grouped together in the UI, enabling analysis of multi-turn conversations:

session_id = Langfuse.Session.new_id()

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

Summary

Types

t()

A trace struct containing all trace attributes.

Functions

get_id(trace)

Returns the trace ID.

get_session_id(trace)

Returns the session ID, or nil if not set.

new(opts)

Creates a new trace and enqueues it for ingestion.

update(trace, opts)

Updates an existing trace and enqueues the update for ingestion.

Types

t()

@type t() :: %Langfuse.Trace{
  id: String.t(),
  input: term(),
  metadata: map() | nil,
  name: String.t(),
  output: term(),
  public: boolean() | nil,
  release: String.t() | nil,
  session_id: String.t() | nil,
  tags: [String.t()] | nil,
  timestamp: DateTime.t(),
  user_id: String.t() | nil,
  version: String.t() | nil
}

A trace struct containing all trace attributes.

The :id is auto-generated using cryptographically secure random bytes if not provided. The :timestamp defaults to the current UTC time.

Functions

get_id(trace)

@spec get_id(t()) :: String.t()

Returns the trace ID.

Examples

iex> trace = Langfuse.Trace.new(name: "test", id: "trace-123")
iex> Langfuse.Trace.get_id(trace)
"trace-123"

get_session_id(trace)

@spec get_session_id(t()) :: String.t() | nil

Returns the session ID, or nil if not set.

Examples

iex> trace = Langfuse.Trace.new(name: "test", session_id: "session-456")
iex> Langfuse.Trace.get_session_id(trace)
"session-456"

iex> trace = Langfuse.Trace.new(name: "test")
iex> Langfuse.Trace.get_session_id(trace)
nil

new(opts)

@spec new(keyword()) :: t()

Creates a new trace and enqueues it for ingestion.

The trace is immediately queued for asynchronous delivery to Langfuse. Returns the trace struct for use in creating nested observations.

Options

  • :name - Name of the trace (required)
  • :id - Custom trace ID. Uses secure random hex if not provided.
  • :user_id - User identifier for filtering and analytics.
  • :session_id - Session ID for grouping related traces.
  • :metadata - Arbitrary metadata as a map.
  • :tags - List of string tags for categorization.
  • :public - Whether the trace is publicly accessible.
  • :input - Input data for the trace.
  • :output - Output data for the trace.
  • :version - Application version string.
  • :release - Release identifier.
  • :timestamp - Custom timestamp. Defaults to DateTime.utc_now/0.

Examples

iex> trace = Langfuse.Trace.new(name: "test")
iex> trace.name
"test"

iex> trace = Langfuse.Trace.new(name: "test", id: "custom-id")
iex> trace.id
"custom-id"

iex> trace = Langfuse.Trace.new(
...>   name: "chat",
...>   user_id: "user-123",
...>   tags: ["prod"]
...> )
iex> trace.user_id
"user-123"
iex> trace.tags
["prod"]

update(trace, opts)

@spec update(
  t(),
  keyword()
) :: t()

Updates an existing trace and enqueues the update for ingestion.

Only the fields provided in opts are updated. Other fields retain their current values.

Options

  • :name - Updated trace name.
  • :user_id - Updated user identifier.
  • :session_id - Updated session ID.
  • :metadata - Updated metadata map (replaces existing).
  • :tags - Updated tags list (replaces existing).
  • :public - Updated public visibility.
  • :input - Updated input data.
  • :output - Updated output data.
  • :version - Updated version string.
  • :release - Updated release identifier.

Examples

iex> trace = Langfuse.Trace.new(name: "test")
iex> trace = Langfuse.Trace.update(trace, output: %{result: "done"})
iex> trace.output
%{result: "done"}

iex> trace = Langfuse.Trace.new(name: "test", tags: ["v1"])
iex> trace = Langfuse.Trace.update(trace, tags: ["v2"])
iex> trace.tags
["v2"]