Module: SwarmSDK::Swarm::LoggingCallbacks

Included in:
SwarmSDK::Swarm
Defined in:
lib/swarm_sdk/swarm/logging_callbacks.rb

Overview

Logging callbacks for swarm events

Extracted from Swarm to reduce class size and eliminate repetitive callback patterns. These callbacks emit structured log events to LogStream for monitoring and debugging.

Instance Method Summary collapse

Instance Method Details

#emit_agent_start_events ⇒ Object

Emit agent_start events for all initialized agents

Called retroactively when agents were initialized before logging was enabled. Emits agent_start events so log stream captures complete agent lifecycle.



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/swarm_sdk/swarm/logging_callbacks.rb', line 74

def emit_agent_start_events
  return unless LogStream.emitter

  # Emit for PRIMARY agents
  @agents.each do |agent_name, chat|
    emit_agent_start_for(agent_name, chat, is_delegation: false)
  end

  # Emit for DELEGATION instances
  @delegation_instances.each do |instance_name, chat|
    base_name = extract_base_name(instance_name)
    emit_agent_start_for(instance_name.to_sym, chat, is_delegation: true, base_name: base_name)
  end

  # Mark as emitted to prevent duplicate emissions
  @agent_start_events_emitted = true
end

#emit_agent_start_for(agent_name, chat, is_delegation:, base_name: nil) ⇒ Object

Emit a single agent_start event

Parameters:

  • agent_name (Symbol) —

    Agent name (or instance name for delegations)

  • chat (Agent::Chat) —

    Agent chat instance

  • is_delegation (Boolean) —

    Whether this is a delegation instance

  • base_name (String, nil) (defaults to: nil) —

    Base agent name for delegations



98
99
100
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
 
# File 'lib/swarm_sdk/swarm/logging_callbacks.rb', line 98

def emit_agent_start_for(agent_name, chat, is_delegation:, base_name: nil)
  base_name ||= agent_name
  agent_def = @agent_definitions[base_name]

  # Build plugin storage info using base name
  plugin_storage_info = {}
  @plugin_storages.each do |plugin_name, agent_storages|
    next unless agent_storages.key?(base_name)

    plugin_storage_info[plugin_name] = {
      enabled: true,
      config: agent_def.respond_to?(plugin_name) ? extract_plugin_config_info(agent_def.public_send(plugin_name)) : nil,
    }
  end

  LogStream.emit(
    type: "agent_start",
    agent: agent_name,
    swarm_id: @swarm_id,
    parent_swarm_id: @parent_swarm_id,
    swarm_name: @name,
    model: agent_def.model,
    provider: agent_def.provider || "openai",
    directory: agent_def.directory,
    system_prompt: agent_def.system_prompt,
    tools: chat.tool_names,
    delegates_to: agent_def.delegates_to,
    plugin_storages: plugin_storage_info,
    is_delegation_instance: is_delegation,
    base_agent: (base_name if is_delegation),
    timestamp: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
  )
end

#emit_retroactive_agent_start_events ⇒ Object

Emit agent_start events if agents were initialized before logging was set up

When agents are initialized BEFORE logging (e.g., via restore()), we need to retroactively set up logging callbacks and emit agent_start events.



43
44
45
46
47
48
49
50
51
52
 
# File 'lib/swarm_sdk/swarm/logging_callbacks.rb', line 43

def emit_retroactive_agent_start_events
  return if !@agents_initialized || @agent_start_events_emitted

  # Setup logging callbacks for all agents (they were skipped during initialization)
  setup_logging_for_all_agents

  # Emit agent_start events now that logging is ready
  emit_agent_start_events
  @agent_start_events_emitted = true
end

#register_default_logging_callbacks ⇒ Object

Register default logging callbacks for all swarm events

Sets up low-priority callbacks that emit structured events to LogStream. These callbacks only fire when LogStream.emitter is set (logging enabled).



14
15
16
17
18
19
 
# File 'lib/swarm_sdk/swarm/logging_callbacks.rb', line 14

def register_default_logging_callbacks
  register_swarm_lifecycle_callbacks
  register_agent_lifecycle_callbacks
  register_tool_execution_callbacks
  register_context_warning_callback
end

#setup_logging(logs) {|entry| ... } ⇒ Object

Setup logging infrastructure for an execution

Parameters:

  • logs (Array) —

    Log collection array

Yields:

  • (entry) —

    Block called for each log entry



25
26
27
28
29
30
31
32
33
34
35
36
37
 
# File 'lib/swarm_sdk/swarm/logging_callbacks.rb', line 25

def setup_logging(logs)
  # Force fresh subscription array for this execution
  Fiber[:log_subscriptions] = []

  # Subscribe to collect logs and forward to user's block
  LogCollector.subscribe do |entry|
    logs << entry
    yield(entry) if block_given?
  end

  # Set LogStream to use LogCollector as emitter
  LogStream.emitter = LogCollector
end

#setup_logging_for_all_agents ⇒ Object

Setup logging callbacks for all initialized agents

Called after restore() when logging is enabled. Sets up logging callbacks for each agent so that subsequent events are captured.



58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/swarm_sdk/swarm/logging_callbacks.rb', line 58

def setup_logging_for_all_agents
  # Setup for PRIMARY agents
  @agents.each_value do |chat|
    chat.setup_logging if chat.respond_to?(:setup_logging)
  end

  # Setup for DELEGATION instances
  @delegation_instances.each_value do |chat|
    chat.setup_logging if chat.respond_to?(:setup_logging)
  end
end