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

VERSION = 
'0.1.7'

Class Method Summary collapse

Class Method Details

.client ⇒ Client

Get a thread-safe singleton client instance

Returns:

  • (Client) —

    Langfuse client



36
37
38
 
# File 'lib/langfuse.rb', line 36

def client
  Thread.current[:langfuse_client] ||= Client.new
end

.configuration ⇒ Object 



25
26
27
 
# File 'lib/langfuse.rb', line 25

def configuration
  @configuration ||= Configuration.new
end

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

Configure the Langfuse client with default settings

Yields:



21
22
23
 
# File 'lib/langfuse.rb', line 21

def configure
  yield(configuration)
end

.flush ⇒ Object

Flush all pending events to Langfuse



140
141
142
143
144
 
# File 'lib/langfuse.rb', line 140

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



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

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



30
31
32
 
# File 'lib/langfuse.rb', line 30

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

.reset! ⇒ Object

Reset the singleton client (mainly for testing)



154
155
156
 
# File 'lib/langfuse.rb', line 154

def reset!
  Thread.current[:langfuse_client] = nil
end

.shutdown ⇒ Object

Shutdown the singleton client



147
148
149
150
151
 
# File 'lib/langfuse.rb', line 147

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



102
103
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
 
# File 'lib/langfuse.rb', line 102

def trace(name = nil, user_id: nil, session_id: nil, input: nil, output: nil,
          metadata: nil, tags: nil, version: nil, release: nil, **kwargs, &block)
  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