Module: SwarmSDK::V3::DebugLog

Defined in:
lib/swarm_sdk/v3/debug_log.rb

Overview

Lightweight debug logging for V3 agents

Activated by setting the ‘DEBUG` or `SWARM_DEBUG` environment variable. Outputs timestamped debug messages to stderr with timing information for performance profiling.

Examples:

Enable debug logging

DEBUG=1 bundle exec ruby my_script.rb

Use in code

DebugLog.log("retriever", "semantic search found 15 cards")
DebugLog.time("retriever", "keyword_search") { keyword_search(query) }

Class Method Summary collapse

Class Method Details

.enabled? ⇒ Boolean

Whether debug logging is enabled

Returns:

  • (Boolean) 


22
23
24
25
26
 
# File 'lib/swarm_sdk/v3/debug_log.rb', line 22

def enabled?
  return @enabled if defined?(@enabled)

  @enabled = ENV["DEBUG"] == "1" || ENV["SWARM_DEBUG"] == "1"
end

.log(component, message) ⇒ void

This method returns an undefined value.

Log a debug message to stderr

Examples:

DebugLog.log("agent", "initializing memory store")

Parameters:

  • component (String) —

    Component name (e.g., “retriever”, “ingestion”)

  • message (String) —

    Debug message



36
37
38
39
40
41
 
# File 'lib/swarm_sdk/v3/debug_log.rb', line 36

def log(component, message)
  return unless enabled?

  timestamp = Time.now.strftime("%H:%M:%S.%L")
  warn("[DEBUG #{timestamp}] [#{component}] #{message}")
end

.time(component, label) { ... } ⇒ Object

Execute a block and log its execution time

Examples:

result = DebugLog.time("retriever", "semantic_search") do
  adapter.vector_search(embedding, top_k: 30)
end

Parameters:

  • component (String) —

    Component name

  • label (String) —

    Operation label

Yields:

  • Block to time

Returns:

  • (Object) —

    Block return value



54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/swarm_sdk/v3/debug_log.rb', line 54

def time(component, label)
  unless enabled?
    return yield
  end

  log(component, "#{label} START")
  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  result = yield
  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
  log(component, "#{label} DONE (#{format_duration(elapsed)})")

  result
end