PHPackages                             tracefast/laravel-ai-observability - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. tracefast/laravel-ai-observability

ActiveLibrary[Logging & Monitoring](/categories/logging)

tracefast/laravel-ai-observability
==================================

OpenInference observability for Laravel AI SDK agents.

v1.2.1(1mo ago)00MITPHPPHP ^8.4CI passing

Since May 30Pushed 1mo agoCompare

[ Source](https://github.com/tracefast/laravel-ai-observability)[ Packagist](https://packagist.org/packages/tracefast/laravel-ai-observability)[ RSS](/packages/tracefast-laravel-ai-observability/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (22)Versions (10)Used By (0)

 [![Laravel AI Observability for TraceFast](art/laravel-ai-observability-tracefast.jpg)](art/laravel-ai-observability-tracefast.jpg)

Laravel AI Observability
========================

[](#laravel-ai-observability)

[![Latest Version on Packagist](https://camo.githubusercontent.com/28ce3cb3cc6cef2a83c446adf3c2d66396e55917a9d10eb6644bab5b5c86fc90/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7472616365666173742f6c61726176656c2d61692d6f62736572766162696c6974792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tracefast/laravel-ai-observability)[![Total Downloads](https://camo.githubusercontent.com/952a2007ceceb11669d2509ad84c3e3108c28c5f43d2455d62384f6538ea22bc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7472616365666173742f6c61726176656c2d61692d6f62736572766162696c6974792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tracefast/laravel-ai-observability)[![PHP Version](https://camo.githubusercontent.com/3ae1ec9e53231e58b210815f08ac8c2a3a38ce88260af25e9158c92d903e6005/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f7472616365666173742f6c61726176656c2d61692d6f62736572766162696c6974792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tracefast/laravel-ai-observability)[![License](https://camo.githubusercontent.com/e2e6f520f087fd144b1a690d0215d9711ec5f87a3e4cf6e7dbfa11ed430802e4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7472616365666173742f6c61726176656c2d61692d6f62736572766162696c6974792e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)

**OpenInference-compatible AI tracing over OpenTelemetry/OTLP for Laravel AI SDK applications.**

This package listens to `laravel/ai` events and exports agent runs, model calls, tool calls, inputs, outputs, token usage, and errors — to your application logs, [TraceFast](https://tracefast.dev), Phoenix, Langfuse, Braintrust, any OTLP-compatible collector, or your local database.

It's designed to be safe to drop into a project on day one. Out of the box it writes structured traces to your existing Laravel log, makes no network calls, and exports through Laravel's deferred callback lifecycle wherever possible. When you're ready for a dedicated collector, switch exporters with a single environment variable.

---

Table of Contents
-----------------

[](#table-of-contents)

- [Why this package](#why-this-package)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Exporters](#exporters)
    - [TraceFast](#tracefast)
    - [Phoenix](#phoenix)
    - [Langfuse](#langfuse)
    - [Braintrust](#braintrust)
    - [Log](#log)
    - [Generic OTLP](#generic-otlp)
    - [Database](#database-exporter)
- [Content Capture](#content-capture)
- [Conversation Correlation](#conversation-correlation)
- [Advanced Configuration](#advanced-configuration)
    - [Production Transport Hardening](#production-transport-hardening)
- [Custom Exporters](#custom-exporters)
- [Testing](#testing)
- [Security](#security)
- [Contributing](#contributing)
- [License](#license)

---

Why this package
----------------

[](#why-this-package)

- **Zero-config by default** — install and start capturing traces immediately; no collector, API key, or extra setup required.
- **OpenInference-compatible over OTLP** — traces use OpenTelemetry/OTLP transport with OpenInference AI span attributes and message conventions.
- **Production-safe export modes** — defer, queue, or background exports so trace delivery never sits in the critical request path.
- **Pluggable exporters** — ship traces to one or more destinations (TraceFast, Phoenix, Langfuse, Braintrust, generic OTLP, your database, or a custom driver) without changing application code.
- **Built-in resilience** — payload limits, bounded retries, gzip compression, and a circuit breaker protect your app if a collector is slow or unreachable.

Requirements
------------

[](#requirements)

RequirementVersionPHP8.4+Laravel12 or 13`laravel/ai`^0.7Installation
------------

[](#installation)

Install the package via Composer:

```
composer require tracefast/laravel-ai-observability
```

That's it — Observability is enabled by default and writes traces to your Laravel log.

To customize exporters or other settings, publish the config file:

```
php artisan vendor:publish --tag=ai-observability-config
```

Quick Start
-----------

[](#quick-start)

The default exporter is `log`, which requires no further configuration:

```
# Optional — this is the default.
AI_OBSERVABILITY_EXPORTER=log
```

> **Note:** V1 captures full LLM input and output by default. See [Content Capture](#content-capture) to disable this.

For production deployments sending traces to a remote collector, keep the default `defer` export mode, or move exports to `queue` or `background` so trace delivery never blocks the request lifecycle. See [Advanced Configuration](#advanced-configuration).

Exporters
---------

[](#exporters)

Set `AI_OBSERVABILITY_EXPORTER` to a single exporter:

```
AI_OBSERVABILITY_EXPORTER=phoenix
```

Or send traces to multiple destinations at once:

```
AI_OBSERVABILITY_EXPORTER=tracefast,braintrust
```

### TraceFast

[](#tracefast)

```
AI_OBSERVABILITY_EXPORTER=tracefast
TRACEFAST_API_KEY=
```

The TraceFast endpoint defaults to `https://collector.tracefast.dev/v1/traces`. Override it only if TraceFast provides a custom collector URL:

```
TRACEFAST_OTEL_ENDPOINT=https://collector.tracefast.dev/v1/traces
```

TraceFast uses `tracefast.platform` to identify the **integration or runtime family** — not your application. This package sends `laravel-ai` by default, allowing TraceFast to group these traces separately from `livekit`, `pipecat`, generic OpenInference, and other sources. Your application name remains in `service.name`, which defaults to `config('app.name')`.

```
# Optional. Keep this as laravel-ai unless you intentionally publish a separate
# integration family.
AI_OBSERVABILITY_PLATFORM=laravel-ai
```

For example, a chatbot running inside a Laravel app named `Acme Support` should keep `tracefast.platform=laravel-ai` and `service.name=Acme Support`. Don't put the chatbot, tenant, or product name in `AI_OBSERVABILITY_PLATFORM` — add that context with [scoped attributes](#conversation-correlation) instead.

### Phoenix

[](#phoenix)

```
AI_OBSERVABILITY_EXPORTER=phoenix
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces
```

### Langfuse

[](#langfuse)

```
AI_OBSERVABILITY_EXPORTER=langfuse
LANGFUSE_OTEL_ENDPOINT=https://cloud.langfuse.com/api/public/otel/v1/traces
LANGFUSE_OTEL_AUTHORIZATION="Basic "
```

### Braintrust

[](#braintrust)

```
AI_OBSERVABILITY_EXPORTER=braintrust
BRAINTRUST_API_KEY=
BRAINTRUST_PARENT=project_name:
```

The Braintrust endpoint defaults to `https://api.braintrust.dev/otel/v1/traces`.

### Log

[](#log)

```
AI_OBSERVABILITY_EXPORTER=log
```

Advanced log options:

```
AI_OBSERVABILITY_LOG_CHANNEL=stack
AI_OBSERVABILITY_LOG_LEVEL=debug
```

### Generic OTLP

[](#generic-otlp)

For Laravel apps that run `php artisan optimize` or otherwise cache config, prefer the package-specific variables so the endpoint and headers are baked into Laravel's cached config:

```
AI_OBSERVABILITY_EXPORTER=otlp
AI_OBSERVABILITY_OTLP_ENDPOINT=https://collector.example.com/v1/traces
AI_OBSERVABILITY_OTLP_HEADERS="Authorization=Bearer "
```

The package also honors standard OTEL environment variables when they're available as real process environment variables. As of v1.1.1, these are also bridged through Laravel's config when present in `.env` during config caching:

```
AI_OBSERVABILITY_EXPORTER=otlp
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://collector.example.com/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer "
```

OTLP payloads include OpenInference and versioned TraceFast metadata, such as `openinference.schema.version`, `tracefast.ai.sdk.version`, `tracefast.ai.package.version`, and OpenInference message attributes such as `llm.input_messages.*` and `llm.output_messages.*` where the Laravel AI SDK exposes the source data.

### Database Exporter

[](#database-exporter)

The database exporter is opt-in and stores traces directly in your application's database.

```
php artisan vendor:publish --tag=ai-observability-migrations
php artisan migrate
```

```
AI_OBSERVABILITY_EXPORTER=database
```

Use a specific connection when needed:

```
AI_OBSERVABILITY_DB_CONNECTION=mysql
```

The migration creates two tables: `ai_observability_traces` and `ai_observability_spans`.

Content Capture
---------------

[](#content-capture)

By default, this package captures full input and output. This may include prompts, system messages, tool arguments, tool results, uploaded content, PII, secrets, and other sensitive business data.

To disable content capture:

```
AI_OBSERVABILITY_CAPTURE_CONTENT=off
```

The package uses OpenInference semantic conventions exclusively and does not emit OTel GenAI semantic convention attributes (`gen_ai.*`). LLM messages, model metadata, and token usage are represented once using OpenInference attributes such as `llm.input_messages.*`, `llm.output_messages.*`, `llm.model_name`, `llm.provider`, and `llm.token_count.*`.

Conversation Correlation
------------------------

[](#conversation-correlation)

Use `AiObservability::withSession()` when your application has its own conversation ID:

```
use Tracefast\LaravelAiObservability\Facades\AiObservability;

$response = AiObservability::withSession(
    sessionId: $conversation->uuid,
    callback: fn () => $agent->prompt($message),
    userId: $user->id,
    attributes: [
        'tenant.id' => (string) $tenant->id,
        'workflow.name' => 'support-triage',
    ],
);
```

Each turn remains its own trace, and every turn carries the same `session.id`. Scoped attributes are copied onto the agent, LLM, and tool spans created while the callback runs. Use them for app-specific business context such as tenant IDs, workflow names, plan names, feature flags, experiment IDs, or your existing conversation ID.

If you don't need the `session.id` or `user.id` helpers, use `AiObservability::withAttributes()` instead:

```
$response = AiObservability::withAttributes([
    'tenant.id' => (string) $tenant->id,
    'workflow.name' => 'support-triage',
], fn () => $agent->prompt($message));
```

Keep scoped attributes separate from resource identity:

- `tracefast.platform` identifies the **integration family**
- `service.name` identifies the **Laravel app or service**
- Custom attributes identify the **business context** for a specific trace or span

Advanced Configuration
----------------------

[](#advanced-configuration)

```
AI_OBSERVABILITY_ENABLED=true
AI_OBSERVABILITY_EXPORT_MODE=defer
AI_OBSERVABILITY_SAMPLE_RATE=1.0
AI_OBSERVABILITY_EXPORT_TIMEOUT=2.0
AI_OBSERVABILITY_EXPORT_CONNECT_TIMEOUT=0.5
AI_OBSERVABILITY_MAX_PAYLOAD_BYTES=1048576
```

`AI_OBSERVABILITY_EXPORT_MODE` accepts `defer`, `sync`, `queue`, or `background`:

ModeBehavior`defer` *(default)*Exports after the response is sent, when Laravel can defer work. Also runs at command and queue job boundaries via Laravel's deferred callback lifecycle.`sync`Exports immediately, in line with the request.`queue`Hands off exports to a normal queue worker.`background`Releases the current PHP worker quickly via a dedicated `background` queue connection.Use `queue` when you want exports handled by a normal queue worker:

```
AI_OBSERVABILITY_EXPORT_MODE=queue
AI_OBSERVABILITY_EXPORT_CONNECTION=redis
AI_OBSERVABILITY_EXPORT_QUEUE=observability
```

Use `background` when your Laravel app has a `background` queue connection and you want to release the current PHP worker quickly:

```
AI_OBSERVABILITY_EXPORT_MODE=background
```

### Production Transport Hardening

[](#production-transport-hardening)

```
AI_OBSERVABILITY_EXPORT_TIMEOUT=2.0
AI_OBSERVABILITY_EXPORT_CONNECT_TIMEOUT=0.5
AI_OBSERVABILITY_MAX_PAYLOAD_BYTES=1048576
AI_OBSERVABILITY_EXPORT_RETRY_ATTEMPTS=1
AI_OBSERVABILITY_EXPORT_RETRY_DELAY_MS=100
AI_OBSERVABILITY_OTLP_COMPRESSION=gzip
AI_OBSERVABILITY_CIRCUIT_BREAKER=true
AI_OBSERVABILITY_CIRCUIT_BREAKER_FAILURE_THRESHOLD=3
AI_OBSERVABILITY_CIRCUIT_BREAKER_OPEN_SECONDS=30
```

- Payloads larger than `AI_OBSERVABILITY_MAX_PAYLOAD_BYTES` are dropped and reported locally instead of being sent.
- OTLP retries are bounded and only intended for transient collector failures (network errors, `408`, `425`, `429`, and `5xx` responses).
- The circuit breaker skips sends for a short window after repeated failures, so a dead collector doesn't keep taxing request workers.

Custom Exporters
----------------

[](#custom-exporters)

Implement the `Exporter` contract to send traces anywhere:

```
use Tracefast\LaravelAiObservability\Contracts\Exporter;
use Tracefast\LaravelAiObservability\Data\Trace;

final class WebhookExporter implements Exporter
{
    public function export(Trace $trace): void
    {
        // Send $trace->toArray() to your destination.
    }
}
```

Register the driver from a service provider:

```
use App\Observability\WebhookExporter;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\ServiceProvider;
use Tracefast\LaravelAiObservability\AiObservability;
use Tracefast\LaravelAiObservability\Contracts\Exporter;

final class AppServiceProvider extends ServiceProvider
{
    public function boot(AiObservability $observability): void
    {
        $observability->extend(
            'webhook',
            fn (Application $app, array $config, string $name): Exporter => new WebhookExporter(),
        );
    }
}
```

Then configure it:

```
'exporters' => [
    'webhook' => [
        'driver' => 'webhook',
    ],
],
```

Testing
-------

[](#testing)

```
composer test
```

Security
--------

[](#security)

If you discover a security vulnerability, please report it responsibly rather than opening a public issue. See [SECURITY.md](SECURITY.md) for details.

Contributing
------------

[](#contributing)

Contributions are welcome. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on submitting issues and pull requests.

License
-------

[](#license)

Laravel AI Observability is open-sourced software licensed under the [MIT license](LICENSE.md).

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance92

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

9

Last Release

37d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/459be098d6e6d274bac2e4d293fc5803e6a8498cf03eb8a8e226d9540b60bb8c?d=identicon)[irajuljain89](/maintainers/irajuljain89)

---

Top Contributors

[![iRajul](https://avatars.githubusercontent.com/u/1621025?v=4)](https://github.com/iRajul "iRajul (1 commits)")

---

Tags

ai-observabilitylaravellaravel-ailaravel-observabilitylaravel-packageobservabilityopeninferenceopentelemetryotlpphptracefasttracinglaravelopentelemetryotlpobservabilitylaravel-ailangfusePhoenixopeninferencebraintrusttracefast

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/tracefast-laravel-ai-observability/health.svg)

```
[![Health](https://phpackages.com/badges/tracefast-laravel-ai-observability/health.svg)](https://phpackages.com/packages/tracefast-laravel-ai-observability)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.3M347](/packages/psalm-plugin-laravel)[laravel/cashier

Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.

2.5k30.2M151](/packages/laravel-cashier)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M133](/packages/roots-acorn)[api-platform/laravel

API Platform support for Laravel

58174.6k17](/packages/api-platform-laravel)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5022.6k](/packages/simplestats-io-laravel-client)[spatie/laravel-health

Monitor the health of a Laravel application

87912.0M177](/packages/spatie-laravel-health)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)