Download the PHP package tracefast/laravel-ai-observability without Composer

Laravel AI Observability

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, 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

• Why this package
• Requirements
• Installation
• Quick Start
• Exporters
  • TraceFast
  • Phoenix
  • Langfuse
  • Braintrust
  • Log
  • Generic OTLP
  • Database
• Content Capture
• Conversation Correlation
• Advanced Configuration
  • Production Transport Hardening
• Custom Exporters
• Testing
• Security
• Contributing
• License

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

Installation

Install the package via Composer:

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:

Quick Start

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

Note: V1 captures full LLM input and output by default. See 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.

Exporters

Set AI_OBSERVABILITY_EXPORTER to a single exporter:

Or send traces to multiple destinations at once:

TraceFast

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

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').

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 instead.

Phoenix

Langfuse

Braintrust

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

Log

Advanced log options:

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:

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:

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

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

Use a specific connection when needed:

The migration creates two tables: ai_observability_traces and ai_observability_spans.

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:

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

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

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:

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

AI_OBSERVABILITY_EXPORT_MODE accepts defer, sync, queue, or background:

Use queue when you want exports handled by a normal queue worker:

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

Production Transport Hardening

• 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

Implement the Exporter contract to send traces anywhere:

Register the driver from a service provider:

Then configure it:

Testing

Security

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

Contributing

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

License

Laravel AI Observability is open-sourced software licensed under the MIT license.