# Module LittleGhost::Events

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Events.html

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.

## Class methods

<a id="method-c-console_output"></a>
### `.console_output`

```ruby
.console_output()
```

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

<a id="method-c-console_output-3D"></a>
### `.console_output=`

```ruby
.console_output=(destination)
```

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

<a id="method-c-context"></a>
### `.context`

```ruby
.context()
```

Copies the current event context.

<a id="method-c-reporter"></a>
### `.reporter`

```ruby
.reporter()
```

Accesses the process-wide reporter.

<a id="method-c-reporter-3D"></a>
### `.reporter=`

```ruby
.reporter=(value)
```

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

<a id="method-c-subscribe"></a>
### `.subscribe`

```ruby
.subscribe(...)
```

Subscribes a process-wide listener.

<a id="method-c-subscribed"></a>
### `.subscribed`

```ruby
.subscribed(listener, &block)
```

Subscribes `listener` only while the block runs.

<a id="method-c-unsubscribe"></a>
### `.unsubscribe`

```ruby
.unsubscribe(...)
```

Unsubscribes a process-wide listener.

<a id="method-c-with_context"></a>
### `.with_context`

```ruby
.with_context(...)
```

Adds event context while a block runs.