Langfuse.Event (Langfuse v0.2.0)

View Source

An event represents a point-in-time occurrence within a trace.

Unlike spans and generations, events have no duration. They mark discrete moments such as user actions, errors, milestones, or any significant occurrence you want to track.

Creating Events

Events are created as children of traces or spans:

trace = Langfuse.trace(name: "user-session")

event = Langfuse.Event.new(trace,
  name: "button-click",
  input: %{button_id: "submit"}
)

Use Cases

Common uses for events include:

  • User interactions (clicks, form submissions)
  • Error occurrences with context
  • State transitions
  • External API calls (when duration isn't important)
  • Logging significant application milestones

Summary

Types

level()

Log level for the observation.

parent()

Valid parent types for an event.

t()

An event struct containing all event attributes.

Functions

get_id(event)

Returns the event ID.

get_trace_id(event)

Returns the trace ID that this event belongs to.

new(parent, opts)

Creates a new event and enqueues it for ingestion.

Types

level()

@type level() :: :debug | :default | :warning | :error

Log level for the observation.

parent()

@type parent() :: Langfuse.Trace.t() | Langfuse.Span.t()

Valid parent types for an event.

t()

@type t() :: %Langfuse.Event{
  id: String.t(),
  input: term(),
  level: level() | nil,
  metadata: map() | nil,
  name: String.t(),
  output: term(),
  parent_observation_id: String.t() | nil,
  start_time: DateTime.t(),
  status_message: String.t() | nil,
  trace_id: String.t(),
  version: String.t() | nil
}

An event struct containing all event attributes.

Events are immutable after creation. The :id is auto-generated if not provided. The :start_time defaults to the current UTC time.

Functions

get_id(event)

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

Returns the event ID.

Examples

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

get_trace_id(event)

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

Returns the trace ID that this event belongs to.

Examples

iex> trace = Langfuse.Trace.new(name: "test", id: "trace-456")
iex> event = Langfuse.Event.new(trace, name: "click")
iex> Langfuse.Event.get_trace_id(event)
"trace-456"

new(parent, opts)

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

Creates a new event and enqueues it for ingestion.

The event is created as a child of the given parent (trace or span). It is immediately queued for asynchronous delivery to Langfuse.

Events are immutable after creation; there is no update function.

Options

  • :name - Name of the event (required)
  • :id - Custom event ID. Uses secure random hex if not provided.
  • :input - Input data associated with the event.
  • :output - Output data associated with the event.
  • :metadata - Arbitrary metadata as a map.
  • :level - Log level: :debug, :default, :warning, or :error.
  • :status_message - Status description.
  • :start_time - Event timestamp. Defaults to DateTime.utc_now/0.
  • :version - Application version string.

Examples

iex> trace = Langfuse.Trace.new(name: "test", id: "trace-1")
iex> event = Langfuse.Event.new(trace, name: "user-click")
iex> event.name
"user-click"
iex> event.trace_id
"trace-1"

iex> trace = Langfuse.Trace.new(name: "test")
iex> event = Langfuse.Event.new(trace,
...>   name: "error",
...>   level: :error,
...>   input: %{error: "Connection failed"},
...>   status_message: "Database unavailable"
...> )
iex> event.level
:error