Open Agent Documentation

Composer Installation

Add the LaraSignal Agent package to your Laravel application using Composer:

composer require larasignal/agent

Interactive Installation Command

Run the interactive installer to configure your project API key, sampling rate, and query recording preferences. Running this command also automatically publishes LaraSignal AI Skills into your workspace:

php artisan larasignal:install

Built-in AI Coding Agent Skills & Rules

When installed, LaraSignal automatically publishes AI Agent Skills to .agents/skills/larasignal-development/SKILL.md and .cursor/rules/larasignal.mdc. AI coding assistants (Cursor, Antigravity, GitHub Copilot, Windsurf) in your codebase automatically learn how and when to use LaraSignal's Programmatic API for measuring 3rd-party API performance, attaching tenant context, and capturing domain events.

php artisan vendor:publish --tag=larasignal-skill

One-Line Non-Interactive Installation

Pass flags directly to automate setup in Dockerfiles, deployment scripts, or CI/CD pipelines:

php artisan larasignal:install --key=ls_live_a1b2c3... --sample-rate=1.0 --record-queries=true --no-interaction

Supported Options

--key= - Set the project API key (LARASIGNAL_KEY).
--sample-rate= - Telemetry sampling rate (e.g. 0.5 for 50%).
--record-queries= - Enable/disable database query capture (true|false).
--ingest-url= - Custom ingestion endpoint (LARASIGNAL_INGEST_URL).

Delivery Modes & Response Latency

LaraSignal is engineered to minimize or eliminate any latency impact on your application's user HTTP responses. You can choose between two delivery strategies based on your architecture:

Default Mode

End-of-Lifecycle Flushing

Telemetry spans are buffered in memory and flushed asynchronously at the end of the HTTP request or queue job lifecycle (app()->terminating()) after the response has already been delivered to the user.

Zero Latency

Background Batch Dispatchers

Set LARASIGNAL_ASYNC=true to write telemetry payloads directly to disk spooling in 0ms. A background worker daemon processes and dispatches batches asynchronously without blocking user HTTP requests.

php artisan larasignal:run --sleep=3

Platform & Multi-Server Compatibility

DigitalOcean App Platform / Docker / AWS ECS

For stateless or multi-container environments where containers have isolated filesystems, use Default Mode (LARASIGNAL_ASYNC=false). Each container sends its telemetry independently via HTTP POST during request termination, requiring zero shared volumes or extra worker containers.

Laravel Forge / Single VPS / Dedicated Servers

On Laravel Forge or dedicated servers, you can use either mode. For zero-latency disk spooling, simply create a new Daemon in your Forge dashboard running php artisan larasignal:run --sleep=3 under the forge user.

Verification & CLI Tools

The agent package includes several helper commands for testing, daemon execution, and deployment operations:

php artisan larasignal:status

Inspect current configuration and API key health status.

php artisan larasignal:test

Dispatch a test telemetry event to confirm ingestion pipeline health.

php artisan larasignal:deployment v1.2.0

Record a deployment release marker in your LaraSignal dashboard.

php artisan larasignal:flush

Re-send spooled offline telemetry batches.

php artisan larasignal:run [--sleep=3] [--once]

Start the LaraSignal background telemetry worker process to continuously process spooled batches.

php artisan larasignal:help

Display CLI help summary and environment variable reference.

Programmatic API

1. Measuring Execution Time

Wrap heavy or critical operations with LaraSignal::measure() to record duration and performance spans:

use LaraSignal\Agent\Facades\LaraSignal;

$result = LaraSignal::measure('stripe-payment', function () {
    return Stripe::charges()->create([
        'amount' => 2500,
        'currency' => 'usd',
    ]);
});

2. Custom Domain Events

Record business-specific events directly into your telemetry pipeline:

LaraSignal::event('OrderCompleted', [
    'order_id' => 109,
    'amount' => 2500,
    'currency' => 'USD',
]);

3. Global Context & Tagging

Attach metadata or tags to all subsequent telemetry spans within the current execution scope:

// Attach contextual metadata
LaraSignal::context(['tenant_id' => $tenant->id, 'plan' => 'pro']);
LaraSignal::tag('checkout', 'high-value');

// Scope temporary context to a closure
LaraSignal::withContext(['batch_id' => 42], function () {
    // Telemetry recorded inside here inherits batch_id = 42
});

4. User Identification

Authenticated users (Auth::user()) are automatically associated. You can also explicitly bind user contexts:

LaraSignal::user($user);

5. Automatic Log Ingestion

Standard Laravel logs (Log::info(), Log::warning(), Log::error()) are automatically ingested as log spans when LARASIGNAL_RECORD_LOGS=true is set.

LaraSignal Open Agent SDK