neuron-monitoring

Neuron AI Monitoring

This skill helps you debug and monitor Neuron AI applications using the framework's event-driven observability system — from local logging with LogListener up to production tracing on the Neuron Cloud platform (setup instructions at the bottom of this document).

The progression is always the same: components emit events → you subscribe listeners. A LogListener writing to stdout and the Neuron Cloud tracing listener are the same mechanism, differing only in where the events go.

Event System Observability

Neuron uses a PSR-14 event dispatcher owned by each Workflow/Agent instance for monitoring all framework events. There is no global state: listeners are registered on the instance and observe every run of it.

Event Emission

All components emit event objects automatically. Every event class lives in NeuronAI\Observability\Events and extends NeuronAI\Observability\ObservabilityEvent:

// Lifecycle (emitted by the executor):
// WorkflowStart, WorkflowEnd, WorkflowNodeStart, WorkflowNodeEnd,
// MiddlewareStart, MiddlewareEnd, BranchStart, BranchEnd,
// WorkflowInterrupted (run paused for external input), AgentError (failure)
//
// Domain (emitted by nodes):
// InferenceStart, InferenceStop, ToolCalling, ToolCalled,
// MessageSaving, MessageSaved, Retrieving, Retrieved,
// PreProcessing, PreProcessed, PostProcessing, PostProcessed,
// SchemaGeneration, SchemaGenerated, Extracting, Extracted, ...

Each event carries its own data plus the emission context stamped by the framework: ->source (the emitting component) and ->branchId (the parallel branch, or null). ->name() returns the string name ('inference-start').

Subscribing Listeners

Listeners are class-keyed with instanceof matching — subscribe to a specific event class, or to ObservabilityEvent::class to receive everything:

use NeuronAI\Observability\Events\InferenceStop;
use NeuronAI\Observability\ObservabilityEvent;

// React to one event type
$agent->subscribe(InferenceStop::class, function (InferenceStop $event): void {
    echo "Inference finished\n";
});

// Catch-all firehose
$agent->subscribe(ObservabilityEvent::class, function (ObservabilityEvent $event): void {
    echo "Event: {$event->name()}\n";
    echo "Source: " . ($event->source !== null ? $event->source::class : 'n/a') . "\n";
});