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/prompt_cache.rb,
lib/langfuse/otel_exporter.rb,
lib/langfuse/span_wrappers.rb,
lib/langfuse/partial_updates.rb,
lib/langfuse/observation_types.rb,
lib/langfuse/template_compiler.rb

Overview

Ruby SDK for Langfuse - Open source LLM engineering platform

Defined Under Namespace

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

Constant Summary collapse

CLIENT_MUTEX = 
Mutex.new
VERSION = 
'0.2.1'

Class Method Summary collapse

Class Method Details

.client ⇒ Client

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

Returns:

  • (Client) —

    Langfuse client



42
43
44
 
# File 'lib/langfuse.rb', line 42

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

.configuration ⇒ Object 



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

def configuration
  @configuration ||= Configuration.new
end

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

Configure the Langfuse client with default settings

Yields:



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

def configure
  yield(configuration)
end

.flush ⇒ Object

Flush all pending events to Langfuse



136
137
138
139
140
 
# File 'lib/langfuse.rb', line 136

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 retries is applied inside the HTTP layer, which retries only transient failures (timeout, network, 429, 5xx), honors Retry-After and backs off with jitter. A missing prompt therefore fails immediately instead of being requested three times.

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



58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/langfuse.rb', line 58

def get_prompt(prompt_name, variables: nil, label: nil, version: nil, cache_ttl_seconds: 60, retries: 2)
  prompt = client.get_prompt(
    prompt_name,
    label: label,
    version: version,
    cache_ttl_seconds: cache_ttl_seconds,
    retries: retries
  )

  variables ? prompt.compile(variables) : prompt
rescue StandardError => e
  warn "Langfuse prompt fetch failed (#{prompt_name}): #{e.message}" if configuration.debug
  nil
end

.new(**kwargs) ⇒ Object

Create a new Langfuse client instance



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

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

.reset! ⇒ Object

Reset the singleton client (mainly for testing)



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

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

.shutdown ⇒ Object

Shutdown the singleton client



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

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
 
# 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)
  # Only trace creation degrades to a NullTrace. An exception raised by the
  # block must propagate: rescuing it here and yielding again would run the
  # caller's block a second time (duplicate LLM calls and billing).
  trace =
    begin
      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
      )
    rescue StandardError => e
      warn "Langfuse trace creation failed: #{e.message}" if configuration.debug
      NullTrace.new
    end

  return trace unless block_given?

  begin
    yield(trace)
  ensure
    flush
  end
end