Module: LittleGhost::Instrumentation

Defined in:
lib/little_ghost/instrumentation.rb

Overview

Instrumentation turns agent work into structured lifecycle notifications. Applications can measure agents, models, tools, workflows, and sessions with the telemetry backend they already use.

class TimingSubscriber < LittleGhost::Instrumentation::Subscriber
def finish(name, attributes)
  puts "#{name}: #{attributes.fetch(:duration_ms)}ms"
end
end

LittleGhost.configure do |config|
config.instrument TimingSubscriber.new
end

A subscriber receives structured attributes when an operation starts, finishes, or emits a point-in-time event. Subscriber failures are reported once and kept separate from agent execution.

Content and trust

Diagnostic content is excluded unless the application installs an explicit Support::ContentCapture policy. One process is one telemetry and content policy boundary; applications that need different exporters or data policies should use separate processes.

Defined Under Namespace

Classes: Bus, Handle, Subscriber

Class Method Summary collapse

Class Method Details

.capture_content ⇒ Object

Installs the process-wide diagnostic content policy.



434
435
 
# File 'lib/little_ghost/instrumentation.rb', line 434

def capture_content(...) = bus.capture_content(...)
# Publishes a point event on the process-wide bus.

.context ⇒ Object

Copies the current instrumentation context.



446
447
 
# File 'lib/little_ghost/instrumentation.rb', line 446

def context = bus.context
# Flushes process-wide subscribers.

.current ⇒ Object

Returns the current fiber's active Handle.



442
443
 
# File 'lib/little_ghost/instrumentation.rb', line 442

def current = bus.current
# Adds attributes while the block runs.

.flush ⇒ Object

Flushes process-wide subscribers.



448
449
 
# File 'lib/little_ghost/instrumentation.rb', line 448

def flush(...) = bus.flush(...)
# Shuts down the process-wide bus.

.instrument ⇒ Object

Wraps a block in a lifecycle operation.



440
441
 
# File 'lib/little_ghost/instrumentation.rb', line 440

def instrument(...) = bus.instrument(...)
# Returns the current fiber's active Handle.

.notifier ⇒ Object

Accesses the process-wide Bus.



414
 
# File 'lib/little_ghost/instrumentation.rb', line 414

def notifier = bus

.notifier=(value) ⇒ Object

Replaces the process-wide bus when it has no active operations.

Raises:

  • (ArgumentError) 


417
418
419
420
421
422
423
424
425
426
427
 
# File 'lib/little_ghost/instrumentation.rb', line 417

def notifier=(value)
  raise ArgumentError, "notifier must be an instrumentation bus" unless value.is_a?(Bus)

  notifier_mutex.synchronize do
    if @bus && !@bus.equal?(value) && @bus.active?
      raise Error, "cannot replace instrumentation notifier with active operations"
    end

    @bus = value
  end
end

.publish ⇒ Object

Publishes a point event on the process-wide bus.



436
437
 
# File 'lib/little_ghost/instrumentation.rb', line 436

def publish(...) = bus.publish(...)
# Starts a lifecycle operation on the process-wide bus.

.shutdown ⇒ Object

Shuts down the process-wide bus.



450
451
 
# File 'lib/little_ghost/instrumentation.rb', line 450

def shutdown(...) = bus.shutdown(...)
# Gets downstream trace fields from process-wide subscribers.

.start ⇒ Object

Starts a lifecycle operation on the process-wide bus.



438
439
 
# File 'lib/little_ghost/instrumentation.rb', line 438

def start(...) = bus.start(...)
# Wraps a block in a lifecycle operation.

.subscribe ⇒ Object

Subscribes a process-wide backend.



430
431
 
# File 'lib/little_ghost/instrumentation.rb', line 430

def subscribe(...) = bus.subscribe(...)
# Unsubscribes a process-wide backend.

.subscribed(subscriber, prepend: false) ⇒ Object

Temporarily subscribes a backend for the block's execution state.



455
456
457
458
459
460
461
462
463
 
# File 'lib/little_ghost/instrumentation.rb', line 455

def subscribed(subscriber, prepend: false)
  unless subscriber.is_a?(Subscriber)
    raise ArgumentError, "instrumentation subscriber must be a LittleGhost::Instrumentation::Subscriber"
  end

  subscribers = ExecutionState[:instrumentation_subscribers] || []
  entry = {subscriber:, prepend:}
  ExecutionState.with(instrumentation_subscribers: subscribers + [entry]) { yield }
end

.trace_context ⇒ Object

Gets downstream trace fields from process-wide subscribers.



452
 
# File 'lib/little_ghost/instrumentation.rb', line 452

def trace_context(...) = bus.trace_context(...)

.unsubscribe ⇒ Object

Unsubscribes a process-wide backend.



432
433
 
# File 'lib/little_ghost/instrumentation.rb', line 432

def unsubscribe(...) = bus.unsubscribe(...)
# Installs the process-wide diagnostic content policy.

.with_context(attributes, &block) ⇒ Object

Adds attributes while the block runs.



444
445
 
# File 'lib/little_ghost/instrumentation.rb', line 444

def with_context(attributes, &block) = bus.with_context(attributes, &block)
# Copies the current instrumentation context.