Class: OllamaAgent::Core::TraceLogger

Inherits:
Object
  • Object
show all
Defined in:
lib/ollama_agent/core/trace_logger.rb

Overview

Structured observability logger for agent runs. Tracks: run_id, step_id, tool_call_id, latency, token usage, retry count, fallback usage, schema failures, user approvals.

Supports three output modes (set via :format):

:human  — colored, readable (default)
:json   — NDJSON file under log_dir
:debug  — human + full payload dump

Constant Summary collapse

FORMATS = 
%i[human json debug].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(log_dir: nil, format: :human, hooks: nil) ⇒ TraceLogger

Returns a new instance of TraceLogger.



22
23
24
25
26
27
28
29
30
 
# File 'lib/ollama_agent/core/trace_logger.rb', line 22

def initialize(log_dir: nil, format: :human, hooks: nil)
  @log_dir = log_dir
  @format  = FORMATS.include?(format.to_sym) ? format.to_sym : :human
  @hooks   = hooks
  @run_id  = "run_#{SecureRandom.hex(8)}"
  @step    = 0

  attach_to_hooks if @hooks
end

Instance Attribute Details

#run_id ⇒ Object (readonly)

Returns the value of attribute run_id.



20
21
22
 
# File 'lib/ollama_agent/core/trace_logger.rb', line 20

def run_id
  @run_id
end

Instance Method Details

#budget_exceeded(reason:) ⇒ Object 



81
82
83
 
# File 'lib/ollama_agent/core/trace_logger.rb', line 81

def budget_exceeded(reason:)
  trace(:budget_exceeded, { reason: reason })
end

#end_run(turns:, budget: nil) ⇒ Object 



45
46
47
 
# File 'lib/ollama_agent/core/trace_logger.rb', line 45

def end_run(turns:, budget: nil)
  trace(:run_end, { turns: turns, budget: budget&.to_h, run_id: @run_id })
end

#fallback_used(from_provider:, to_provider:, reason:) ⇒ Object 



73
74
75
 
# File 'lib/ollama_agent/core/trace_logger.rb', line 73

def fallback_used(from_provider:, to_provider:, reason:)
  trace(:provider_fallback, { from: from_provider, to: to_provider, reason: reason })
end

#loop_detected(summary:) ⇒ Object 



77
78
79
 
# File 'lib/ollama_agent/core/trace_logger.rb', line 77

def loop_detected(summary:)
  trace(:loop_detected, { summary: summary })
end

#retry_attempt(attempt:, delay_ms:, error:) ⇒ Object 



68
69
70
71
 
# File 'lib/ollama_agent/core/trace_logger.rb', line 68

def retry_attempt(attempt:, delay_ms:, error:)
  trace(:http_retry, { attempt: attempt, delay_ms: delay_ms,
                       error: error.class.name, message: error.message })
end

#schema_failure(tool:, errors:) ⇒ Object 



60
61
62
 
# File 'lib/ollama_agent/core/trace_logger.rb', line 60

def schema_failure(tool:, errors:)
  trace(:schema_failure, { tool: tool, errors: errors })
end

#start_run(query: nil) ⇒ Object 



41
42
43
 
# File 'lib/ollama_agent/core/trace_logger.rb', line 41

def start_run(query: nil)
  trace(:run_start, { query: query, run_id: @run_id })
end

#tool_call(name:, args:, turn:, call_id: nil) ⇒ Object 



49
50
51
52
53
 
# File 'lib/ollama_agent/core/trace_logger.rb', line 49

def tool_call(name:, args:, turn:, call_id: nil)
  @step += 1
  trace(:tool_call, { name: name, args: args, turn: turn,
                      step: @step, call_id: call_id || step_id })
end

#tool_result(name:, result:, turn:, latency_ms: nil, call_id: nil) ⇒ Object 



55
56
57
58
 
# File 'lib/ollama_agent/core/trace_logger.rb', line 55

def tool_result(name:, result:, turn:, latency_ms: nil, call_id: nil)
  trace(:tool_result, { name: name, bytes: result.to_s.bytesize,
                        turn: turn, latency_ms: latency_ms, call_id: call_id })
end

#trace(event, payload = {}) ⇒ Object

Emit a structured trace event.

Parameters:

  • event (Symbol) —

    event name

  • payload (Hash) (defaults to: {}) 


35
36
37
38
39
 
# File 'lib/ollama_agent/core/trace_logger.rb', line 35

def trace(event, payload = {})
  entry = build_entry(event, payload)
  write_entry(entry)
  entry
end

#user_approval(tool:, approved:) ⇒ Object 



64
65
66
 
# File 'lib/ollama_agent/core/trace_logger.rb', line 64

def user_approval(tool:, approved:)
  trace(:user_approval, { tool: tool, approved: approved })
end