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/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, Prompt, PromptTemplate, RateLimitError, Score, Span, TimeoutError, Trace, ValidationError

Constant Summary collapse

VERSION = 
'0.1.6'

Class Method Summary collapse

Class Method Details

.client ⇒ Client

Get a thread-safe singleton client instance

Returns:

  • (Client) —

    Langfuse client



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

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

.configuration ⇒ Object 



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

def configuration
  @configuration ||= Configuration.new
end

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

Configure the Langfuse client with default settings

Yields:



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

def configure
  yield(configuration)
end

.flush ⇒ Object

Flush all pending events to Langfuse



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

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



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

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



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

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

.reset! ⇒ Object

Reset the singleton client (mainly for testing)



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

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

.shutdown ⇒ Object

Shutdown the singleton client



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

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



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

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