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.



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

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

.context ⇒ Object

Copies the current instrumentation context.



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

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

.current ⇒ Object

Returns the current fiber's active Handle.



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

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

.flush ⇒ Object

Flushes process-wide subscribers.



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

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

.instrument ⇒ Object

Wraps a block in a lifecycle operation.



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

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

.notifier ⇒ Object

Accesses the process-wide Bus.



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

def notifier = bus

.notifier=(value) ⇒ Object

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

Raises:

  • (ArgumentError) 


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

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.



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

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

.shutdown ⇒ Object

Shuts down the process-wide bus.



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

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

.start ⇒ Object

Starts a lifecycle operation on the process-wide bus.



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

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

.subscribe ⇒ Object

Subscribes a process-wide backend.



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

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

.subscribed(subscriber, prepend: false) ⇒ Object

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



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

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.



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

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

.unsubscribe ⇒ Object

Unsubscribes a process-wide backend.



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

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

.with_context(attributes, &block) ⇒ Object

Adds attributes while the block runs.



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

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