> For the complete documentation index, see [llms.txt](https://docs.neuron-ai.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/observability.md).

# 监控与调试

实时监控你的 AI Agents、RAG 和工作流。

该 [Inspector](https://inspector.dev/) 团队为 Neuron 设计了内置的可观测性功能，因此你可以监控正在运行的 AI 代理，帮助你自信地维护生产级实现。

### 订阅监听器

监听器以类为键，并使用 instanceof 匹配——订阅特定事件类，或者订阅 `ObservabilityEvent::class` 以接收全部事件：

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

// 对一种事件类型做出响应
$agent->subscribe(InferenceStop::class, function (InferenceStop $event): void {
    // 执行一些操作...
});

// 捕获所有事件
$agent->subscribe(ObservabilityEvent::class, function (ObservabilityEvent $event): void {
    echo "事件：{$event->name()}\n";
    echo "来源：" . ($event->source !== null ? $event->source::class : 'n/a') . "\n";
});
```

#### 自定义事件

通过 `Node::emit()` 从节点中发出你自己的事件——事件对象就是负载。继承 `ObservabilityEvent` :

```php
use NeuronAI\Observability\ObservabilityEvent;

class DocumentScored extends ObservabilityEvent
{
    public function __construct(public string $documentId, public float $score)
    {
    }
}

// 在节点内部
$this->emit(new DocumentScored($doc->id, $score));

// 任意位置
$workflow->subscribe(DocumentScored::class, fn (DocumentScored $e) => $metrics->gauge('score', $e->score));
```

#### 集成宿主框架

将每个事件转发到应用范围的 PSR-14 分发器（Symfony、Laravel 的 PSR 桥接、League\Event）——Neuron 事件会变成常规的应用事件：

```php
$agent->setEventDispatcher($appEventDispatcher);
```

### 安装 Inspector <a href="#install-inspector" id="install-inspector"></a>

将你的 Neuron AI Agents、RAG 或 Workflow 连接到 Inspector 监控面板：

{% embed url="<https://docs.inspector.dev/guides/neuron-ai>" %}

在将你的应用连接到 Inspector 后，当你的代理执行时，你将能够查看其推理步骤、工具调用等详细信息。

<figure><img src="https://content.gitbook.com/content/GHx4l2LknIex7vFIUg1R/blobs/c3hAqFgQsCv0wAgHHHVS/inspector-neuron-monitoring-timeline.png" alt=""><figcaption></figcaption></figure>

如果你想监控整个应用，可以根据你的开发环境安装 Inspector 包。我们提供以下集成包： [PHP](https://github.com/inspector-apm/inspector-php), [Laravel](https://github.com/inspector-apm/inspector-laravel), [Symfony](https://github.com/inspector-apm/inspector-symfony), [CodeIgniter](https://github.com/inspector-apm/inspector-codeigniter), [Drupal](https://docs.inspector.dev/guides/drupal)。请在我们的 [GitHub 组织](https://github.com/inspector-apm).

### 创建摄取密钥

要创建摄取密钥，请前往 [**Inspector 仪表板**](https://app.inspector.dev/register) 并创建一个新应用。

{% hint style="success" %}
如需任何额外支持，请在仪表板中的实时聊天里联系我们。我们很乐意倾听你的使用体验，寻找新的潜在改进，并随着时间推移让工具变得更好。
{% endhint %}

### 注册 Inspector 监听器

如果你的应用没有针对 PHP 环境变量的特定集成，你可以将 `InspectorListener` 组件以编程方式注入到代理中，并传入在仪表板中生成的摄取密钥：

```php
use NeuronAI\Observability\InspctorObserver;

/*
 * 在运行时注入
 */
$message = MyAgent::make()
    ->subscribe(
        ObservabilityEvent::class, 
        InspctorObserver::instance('INSPECTOR_INGESTION_KEY')
    )
    ->chat(...)
    ->getMessage();
    
/*
 * 在代理构造函数中只需设置一次监听器
 */
class MyAgent extends Agent
{
    public function __construct()
    {
        parent::__construct();
        
        $this->subscribe(
            ObservabilityEvent::class, 
            InspctorObserver::instance('INSPECTOR_INGESTION_KEY')
        );
    }
}
```

## 日志记录

如果你想将代理活动上报到日志系统，可以附加内置的 `LogListener` 到你的代理中，传入一个 PSR `LoggerInterface` 兼容的日志记录器实例，例如 monolog：

```php
use NeuronAI\Observability\LogListener;
use NeuronAI\Observability\ObservabilityEvent;

$message = MyAgent::make()
    ->subscribe(ObservabilityEvent::class, new LogListener($logger))
    ->chat(...)
    ->getMessage();
```

所有内部事件及其负载都会被记录。