Class: LangGraphRB::Observers::LangfuseObserver

Inherits:
BaseObserver
  • Object
show all
Defined in:
lib/langgraph_rb/observers/langfuse.rb

Overview

Langfuse observer that captures graph, node, and LLM events.

  • Creates a Langfuse trace for each graph run (thread_id)
  • Creates spans per node execution and links LLM generations to spans
  • Thread-safe and resilient to Langfuse client errors

Instance Method Summary collapse

Methods inherited from BaseObserver

#on_checkpoint_saved, #on_command_processed, #on_interrupt, #on_state_change, #on_step_complete, #shutdown

Constructor Details

#initialize(name: 'langgraph-run') ⇒ LangfuseObserver

Returns a new instance of LangfuseObserver.



10
11
12
13
14
15
16
17
18
19
 
# File 'lib/langgraph_rb/observers/langfuse.rb', line 10

def initialize(name: 'langgraph-run')
  @name = name
  @trace = nil
  @trace_mutex = Mutex.new

  # Maintain a stack per node_name to safely handle parallel executions
  # { Symbol(String) => [ { span: <Span>, generation: <Generation>|nil } ] }
  @records_by_node = Hash.new { |h, k| h[k] = [] }
  @records_mutex = Mutex.new
end

Instance Method Details

#on_graph_end(event) ⇒ Object 



28
29
30
31
32
 
# File 'lib/langgraph_rb/observers/langfuse.rb', line 28

def on_graph_end(event)
  return unless @trace
  Langfuse.trace(id: @trace.id, output: safe_state(event.initial_state))
rescue => _e
end

#on_graph_start(event) ⇒ Object

Graph lifecycle



22
23
24
25
26
 
# File 'lib/langgraph_rb/observers/langfuse.rb', line 22

def on_graph_start(event)
  ensure_trace!(event)
rescue => _e
  # Swallow observer errors to avoid impacting execution
end

#on_llm_error(data, node_name) ⇒ Object 



168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/langgraph_rb/observers/langfuse.rb', line 168

def on_llm_error(data, node_name)
  record = with_records_lock do
    stack = @records_by_node[node_name]
    stack.empty? ? nil : stack[-1]
  end
  return unless record && record[:generation]

  generation = record[:generation]        
  generation.output = data[:error]
  generation.end_time = Time.now.utc
  Langfuse.update_generation(generation)

  with_records_lock do
    record[:generation] = nil
  end
rescue => _e
end

#on_llm_request(data, node_name) ⇒ Object

LLM lifecycle (called directly by LLM clients)



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/langgraph_rb/observers/langfuse.rb', line 92

def on_llm_request(data, node_name)
  record = with_records_lock do
    stack = @records_by_node[node_name]
    stack.empty? ? nil : stack[-1]
  end
  return unless record && record[:span]

  # Prefer normalized payload from LLMBase implementations (e.g., ChatOpenAI)
  input_payload = if data.is_a?(Hash)
    data[:input] || data[:messages] || (data[:request] && data[:request][:messages])
  else
    data
  end

  generation = Langfuse.generation(
    name: "llm-request-#{node_name}",
    trace_id: @trace&.id,
    parent_observation_id: record[:span].id,
    model: data[:model],
    input: input_payload,
    metadata: (data.respond_to?(:to_h) ? data.to_h : data)
  )

  with_records_lock do
    record[:generation] = generation
  end
rescue => _e
end

#on_llm_response(data, node_name) ⇒ Object 



121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
 
# File 'lib/langgraph_rb/observers/langfuse.rb', line 121

def on_llm_response(data, node_name)
  record = with_records_lock do
    stack = @records_by_node[node_name]
    stack.empty? ? nil : stack[-1]
  end
  return unless record && record[:generation]

  generation = record[:generation]

  if data.is_a?(Hash)
    # Prefer normalized payload keys first
    if data.key?(:output)
      generation.output = data[:output]
    else
      # Fallback to OpenAI-style response structure
      generation.output = data.dig(:choices, 0, :message, :content)
    end

    # Usage: support both normalized top-level and OpenAI usage block
    prompt_tokens = data[:prompt_tokens] || data.dig(:usage, :prompt_tokens)
    completion_tokens = data[:completion_tokens] || data.dig(:usage, :completion_tokens)
    total_tokens = data[:total_tokens] || data.dig(:usage, :total_tokens)

    if prompt_tokens || completion_tokens || total_tokens
      begin
        generation.usage = Langfuse::Models::Usage.new(
          prompt_tokens: prompt_tokens,
          completion_tokens: completion_tokens,
          total_tokens: total_tokens
        )
      rescue => _e
        # best-effort usage mapping
      end
    end
  else
    generation.output = data
  end

  generation.end_time = Time.now.utc
  Langfuse.update_generation(generation)

  with_records_lock do
    record[:generation] = nil
  end
rescue => _e
end

#on_node_end(event) ⇒ Object 



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

def on_node_end(event)
  return if event.node_name == :__start__

  record = with_records_lock do
    @records_by_node[event.node_name].pop
  end

  span = record && record[:span]
  return unless span

  data = event.to_h
  span.input = safe_state(data[:state_before])
  span.output = safe_state(data[:state_after])
  span.metadata = data
  span.end_time = Time.now.utc
  Langfuse.update_span(span)
rescue => _e
end

#on_node_error(event) ⇒ Object 



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/langgraph_rb/observers/langfuse.rb', line 75

def on_node_error(event)
  return if event.node_name == :__start__

  record = with_records_lock do
    @records_by_node[event.node_name].pop
  end

  span = record && record[:span]
  return unless span

  span.metadata = event.to_h
  span.end_time = Time.now.utc
  Langfuse.update_span(span)
rescue => _e
end

#on_node_start(event) ⇒ Object

Node lifecycle



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/langgraph_rb/observers/langfuse.rb', line 35

def on_node_start(event)
  return if event.node_name == :__start__

  trace = ensure_trace!(event)
  return unless trace

  span = Langfuse.span(
    name: event.node_name.to_s,
    trace_id: trace.id,
    metadata: event.to_h
  )

  # Track record on a stack keyed by node_name
  with_records_lock do
    @records_by_node[event.node_name] << { span: span, generation: nil }
  end

  Langfuse.update_span(span)
rescue => _e
end