Download the PHP package kanary/laravel-ai-observatory without Composer

AI Observatory

AI Observatory is an independent, open-source observability and debugging package for applications using the official Laravel AI SDK.

AI prompts and responses can contain sensitive information. Review capture and redaction settings before enabling this package in production.

Version 1.0.0 is the first stable release. AI Observatory follows semantic versioning for its documented public APIs while keeping Laravel AI SDK compatibility isolated behind source-verified adapters.

Requirements

• PHP 8.3 or newer
• Laravel 12 or 13
• laravel/ai 0.10.x
• MySQL 8+, PostgreSQL 14+, or SQLite

Versioning and stability

The documented facade methods, extension contracts, configuration keys, Artisan commands, and stored trace schema are covered by the 1.x backwards compatibility commitment. Breaking changes to those surfaces require a new major release.

The Laravel AI SDK remains pre-1.0. Adapter internals may change as the SDK evolves, but each supported SDK range is source verified and contract tested. Untested or unsupported SDK versions are reported explicitly by ai-observatory:status.

Documentation

Read the Laravel AI Observatory documentation. It covers installation, basic usage, trace concepts, privacy, recording modes, dashboard workflows, advanced extensions, and complete configuration and command references. The package-owned Markdown source is available in docs.

Installation

The install command publishes one idempotent, ordered migration set. Re-running the command does not create duplicate migrations.

The package uses its own tables and does not depend on Laravel Telescope internals. Foreign keys use restrictive deletion rules; maintenance commands delete children explicitly in bounded transactions.

Trace dashboard

Open /ai-observatory/traces to search and filter recorded AI operations. The trace list includes status, agent, provider/model, tool count, token usage, estimated cost, duration, user, tenant, and feature context.

Trace details display an ordered parent-child timeline. Select a span to inspect its request, response, tool data, usage, metadata, and error information. Stored payloads are redacted and size-limited again before they are returned to the dashboard.

The React dashboard and its compiled assets are served directly by the package; host applications do not need Node.js or an npm build step. Change the route prefix with:

Production authorization

Recording and dashboard access default to local environments. Production recording must be enabled explicitly:

Authorize future Observatory routes with the viewAiObservatory gate or a request callback:

Sampling

Sampling is decided once at trace start, and every child span follows that decision. Unsampled traces are buffered after redaction and payload limiting when failed- or slow-trace promotion is enabled.

An interrupted unsampled trace that never emits a completion event cannot be promoted. Scoped recorder state prevents that buffer from leaking into later Octane requests or queue jobs.

Estimated costs

Prices are configured locally and are never fetched automatically:

Unknown or incomplete prices produce null, never a zero-cost estimate. Trace totals are calculated only when every model span is priced in the same currency.

Recording modes

Synchronous recording is the local default. Production applications can defer database work until after the response or send one normalized event batch to a queue:

Supported modes are sync, after_response, and queue. Prompt, response, and tool payloads are redacted and size-limited before deferred or queued persistence. Queue payloads contain package DTO arrays, never Laravel AI SDK event objects. Batches are compressed before dispatch. If one still exceeds the safe queue-payload limit, the deferred callback persists it locally instead of silently dropping it. Queue failures do not affect the host AI response.

Queue context

Laravel Context carries Observatory correlation data in queue payloads. Add the provided middleware to application jobs that invoke AI:

Add business context around dispatch or execution:

You may also set correlation fields directly with AiObservatory::user($user), AiObservatory::tenant($organization), and AiObservatory::feature('ticket-reply'). Model identities are normalized into the indexed user and tenant columns used by dashboard filters.

The middleware restores the context for the job and clears it afterward so long-lived workers do not leak correlation data.

Streaming

Completed streams record request start, first-token, and response-completion timestamps plus time to first token. Stream text is buffered into the model span; individual token records are not created.

When a client disconnects before the Laravel AI SDK emits AgentStreamed, the running trace remains incomplete. Recover stale operations with:

Recovered traces and spans are marked cancelled and retain recovery metadata.

Privacy and redaction

Sensitive keys are masked recursively, explicit dot paths support wildcards, and oversized payloads are replaced with truncation metadata. Embedding vectors are not captured by default.

Review capture, redaction, and payloads in the published config/ai-observatory.php before enabling recording outside local environments.

Configuration

The published configuration controls enablement, dashboard path, database connection, recording mode, queue, capture switches, payload limits, redaction, sampling, retention, recovery, middleware, and the local pricing catalog. Environment variables cover the common deployment settings; use the config file for structured redaction paths and model prices.

Custom SDK adapters

SDK event objects are never persisted directly. A custom adapter can translate an application or future SDK event into the package's stable internal DTOs:

Adapters implement Kanary\AiObservatory\Adapters\AiSdkEventAdapter. Unknown events are ignored; enable AI_OBSERVATORY_DEBUG=true to log compatibility and recorder diagnostics.

Demo workbench

The included Orchestra Testbench application generates realistic traces with Laravel AI SDK fakes and needs no API keys:

See workbench/README.md for real-provider opt-in notes.

Maintenance

Prune and clear delete events, spans, and traces explicitly in bounded transactions. Foreign keys restrict accidental parent deletion.

SDK compatibility

See the verified SDK event inventory.

An SDK version outside the tested range is reported as untested or unsupported by ai-observatory:status; it is never silently presented as compatible.

Troubleshooting

See Troubleshooting for missing traces, queue, database, authorization, and stale-stream checks.

Security and contributing

Report vulnerabilities according to SECURITY.md. Development setup, source-verification rules, and the required quality checks are in CONTRIBUTING.md. Release changes are tracked in CHANGELOG.md.

Acknowledgments

Documentation inspired by Spatie.

Current limitations

• SDK compatibility is verified only for laravel/ai 0.10.1.
• Provider failover is recorded only to the extent exposed by official SDK events.
• Laravel AI SDK 0.10.1 has no terminal agent- or tool-failure event. Failed starts remain incomplete until request cleanup and stale recovery.
• Interrupted streams require stale-trace recovery.
• Automatic user, tenant, and feature resolver callbacks are planned; use the context or direct correlation APIs today.
• Prices are application-managed estimates and are never synchronized online.