module LittleGhost::Events

Events lets an application react to noteworthy agent activity without coupling LittleGhost to a logger or event backend. Listeners can feed local diagnostics, alerts, or an application’s own event pipeline.

class WarningCollector
  attr_reader :events

  def initialize
    @events = []
  end

  def emit(event)
    events << event
  end
end

warnings = WarningCollector.new
LittleGhost::Events.subscribe(warnings) do |event|
  %i[warn error].include?(event[:level])
end
LittleGhost::Events.warn("support.case.stalled", case_id: "case-42")
warnings.events.last[:name] # => "support.case.stalled"

Events describe point-in-time facts. Instrumentation measures work that has a start and finish. Payloads are copied, limited to JSON-safe values, and delivered with context local to the current execution. A broken listener never breaks the operation that emitted the event.

Constants

LEVELS: Severity levels accepted by .emit and its convenience methods.

Public Class Methods

console_output ()

Source

# File lib/little_ghost/events.rb, line 207
def console_output
  reporter_mutex.synchronize { @console_output }
end

The process-wide JSON-line console destination, or nil when console delivery is disabled.

console_output= (destination)

Source

# File lib/little_ghost/events.rb, line 214
def console_output=(destination)
  unless [nil, :stdout, :stderr].include?(destination)
    raise ArgumentError, "event log destination must be :stdout, :stderr, or nil"
  end

  reporter_mutex.synchronize do
    @reporter ||= Reporter.new
    @reporter.unsubscribe(@console_listener) if @console_listener
    @console_output = destination
    @console_listener = destination && ConsoleListener.new(io: (destination == :stdout) ? $stdout : $stderr)
    @reporter.subscribe(@console_listener) if @console_listener
  end
end

Selects :stdout, :stderr, or nil as the process-wide JSON-line console destination. Replacing the destination leaves other listeners unchanged.

context ()

Source

# File lib/little_ghost/events.rb, line 235
def context = reporter.context

Copies the current event context.

reporter ()

Source

# File lib/little_ghost/events.rb, line 190
def reporter
  reporter_mutex.synchronize { @reporter ||= Reporter.new }
end

Accesses the process-wide reporter.

reporter= (value)

Source

# File lib/little_ghost/events.rb, line 195
def reporter=(value)
  raise ArgumentError, "reporter must be an event reporter" unless value.is_a?(Reporter)

  reporter_mutex.synchronize do
    @reporter&.unsubscribe(@console_listener) if @console_listener
    @reporter = value
    @reporter.subscribe(@console_listener) if @console_listener
  end
end

Replaces the process-wide reporter. Existing references are unaffected.

subscribed (listener, &block)

Source

# File lib/little_ghost/events.rb, line 249
def subscribed(listener, &block)
  raise ArgumentError, "event listener must respond to emit" unless listener.respond_to?(:emit)

  listeners = ExecutionState[:little_ghost_event_listeners] || []
  entry = {listener:, filter: nil}
  ExecutionState.with(little_ghost_event_listeners: listeners + [entry], &block)
end

Subscribes listener only while the block runs.

unsubscribe (...)

Source

# File lib/little_ghost/events.rb, line 231
def unsubscribe(...) = reporter.unsubscribe(...)

Unsubscribes a process-wide listener.

with_context (...)

Source

# File lib/little_ghost/events.rb, line 233
def with_context(...) = reporter.with_context(...)

Adds event context while a block runs.