Module: Langfuse

Defined in:
lib/langfuse.rb,
lib/langfuse/span.rb,
lib/langfuse/event.rb,
lib/langfuse/trace.rb,
lib/langfuse/utils.rb,
lib/langfuse/client.rb,
lib/langfuse/errors.rb,
lib/langfuse/prompt.rb,
lib/langfuse/version.rb,
lib/langfuse/evaluation.rb,
lib/langfuse/generation.rb,
lib/langfuse/null_objects.rb,
lib/langfuse/otel_exporter.rb,
lib/langfuse/observation_types.rb

Overview

Ruby SDK for Langfuse - Open source LLM engineering platform

Defined Under Namespace

Modules: Evaluators, ObservationType, Utils Classes: APIError, AuthenticationError, ChatPromptTemplate, Client, Configuration, Error, Evaluation, Event, Generation, NetworkError, NullEvent, NullGeneration, NullSpan, NullTrace, OtelExporter, Prompt, PromptTemplate, RateLimitError, Score, Span, TimeoutError, Trace, ValidationError

Constant Summary collapse

CLIENT_MUTEX = 
Mutex.new
VERSION = 
'0.2.0'

Class Method Summary collapse

Class Method Details

.client ⇒ Client

Get a process-wide, thread-safe singleton client instance

Returns:

  • (Client) —

    Langfuse client



38
39
40
 
# File 'lib/langfuse.rb', line 38

def client
  @client || CLIENT_MUTEX.synchronize { @client ||= Client.new }
end

.configuration ⇒ Object 



27
28
29
 
# File 'lib/langfuse.rb', line 27

def configuration
  @configuration ||= Configuration.new
end

.configure {|configuration| ... } ⇒ Object

Configure the Langfuse client with default settings

Yields:



23
24
25
 
# File 'lib/langfuse.rb', line 23

def configure
  yield(configuration)
end

.flush ⇒ Object

Flush all pending events to Langfuse



142
143
144
145
146
 
# File 'lib/langfuse.rb', line 142

def flush
  client.flush
rescue StandardError => e
  warn "Langfuse flush failed: #{e.message}" if configuration.debug
end

.get_prompt(prompt_name, variables: nil, label: nil, version: nil, cache_ttl_seconds: 60, retries: 2) ⇒ String, ...

Get a prompt and optionally compile it with variables

Parameters:

  • prompt_name (String) —

    prompt name

  • variables (Hash) (defaults to: nil) —

    optional variables for compilation

  • label (String) (defaults to: nil) —

    optional prompt label (defaults to 'production' or 'latest')

  • version (Integer) (defaults to: nil) —

    optional prompt version

  • cache_ttl_seconds (Integer) (defaults to: 60) —

    cache TTL in seconds (default: 60)

  • retries (Integer) (defaults to: 2) —

    number of retries on failure (default: 2)

Returns:

  • (String, Prompt, nil) —

    compiled prompt string if variables provided, Prompt object otherwise, nil on failure



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse.rb', line 50

def get_prompt(prompt_name, variables: nil, label: nil, version: nil, cache_ttl_seconds: 60, retries: 2)
  attempts = 0

  begin
    attempts += 1
    prompt = client.get_prompt(prompt_name, label: label, version: version, cache_ttl_seconds: cache_ttl_seconds)

    if variables
      prompt.compile(variables)
    else
      prompt
    end
  rescue StandardError => e
    if attempts <= retries
      sleep_time = (2**(attempts - 1)) * 0.1 # Exponential backoff: 0.1s, 0.2s, 0.4s...
      warn "Langfuse prompt fetch failed (#{prompt_name}), retrying in #{sleep_time}s... (attempt #{attempts}/#{retries + 1})" if configuration.debug
      sleep(sleep_time)
      retry
    end

    warn "Langfuse prompt fetch failed (#{prompt_name}): #{e.message}" if configuration.debug
    nil
  end
end

.new(**kwargs) ⇒ Object

Create a new Langfuse client instance



32
33
34
 
# File 'lib/langfuse.rb', line 32

def new(**kwargs)
  Client.new(**kwargs)
end

.reset! ⇒ Object

Reset the singleton client (mainly for testing)



156
157
158
 
# File 'lib/langfuse.rb', line 156

def reset!
  CLIENT_MUTEX.synchronize { @client = nil }
end

.shutdown ⇒ Object

Shutdown the singleton client



149
150
151
152
153
 
# File 'lib/langfuse.rb', line 149

def shutdown
  client.shutdown
rescue StandardError => e
  warn "Langfuse shutdown failed: #{e.message}" if configuration.debug
end

.trace(name = nil, user_id: nil, session_id: nil, input: nil, output: nil, metadata: nil, tags: nil, version: nil, release: nil, **kwargs) {|Trace, NullTrace| ... } ⇒ Object

Create a trace and optionally execute a block with it When a block is given, the trace is yielded and flush is called automatically after the block If trace creation fails, a NullTrace is yielded to ensure the block still executes

Examples:

Block-based usage with automatic flush

Langfuse.trace("my-trace", user_id: "user-1") do |trace|
  generation = trace.generation(name: "openai", model: "gpt-4", input: messages)
  response = call_openai(...)
  generation.end(output: response, usage: response.usage)
  trace.update(output: response)
end

Direct usage without block

trace = Langfuse.trace("my-trace")
# ... work with trace
Langfuse.flush

Parameters:

  • name (String) (defaults to: nil) —

    trace name

  • user_id (String) (defaults to: nil) —

    optional user identifier

  • session_id (String) (defaults to: nil) —

    optional session identifier

  • input (Object) (defaults to: nil) —

    optional input data

  • output (Object) (defaults to: nil) —

    optional output data

  • metadata (Hash) (defaults to: nil) —

    optional metadata

  • tags (Array) (defaults to: nil) —

    optional tags

  • version (String) (defaults to: nil) —

    optional version

  • release (String) (defaults to: nil) —

    optional release

Yields:

Returns:

  • (Object) —

    block return value if block given, trace otherwise



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/langfuse.rb', line 104

def trace(name = nil, user_id: nil, session_id: nil, input: nil, output: nil,
          metadata: nil, tags: nil, version: nil, release: nil, **kwargs)
  trace = client.trace(
    name: name,
    user_id: user_id,
    session_id: session_id,
    input: input,
    output: output,
    metadata: metadata,
    tags: tags,
    version: version,
    release: release,
    **kwargs
  )

  if block_given?
    begin
      result = yield(trace)
      result
    ensure
      flush
    end
  else
    trace
  end
rescue StandardError => e
  warn "Langfuse trace creation failed: #{e.message}" if configuration.debug

  # If block given, execute with NullTrace to ensure code continues
  if block_given?
    null_trace = NullTrace.new
    yield(null_trace)
  else
    NullTrace.new
  end
end