Download the PHP package larasignal/agent without Composer

LaraSignal Agent

Privacy-first Laravel telemetry agent for LaraSignal.

Compatibility

LaraSignal supports PHP 8.2 or newer and Laravel 10, 11, 12, and 13. The package adapts queue and HTTP event telemetry to each framework version, collecting newer event metadata only when Laravel exposes it.

Interactive Installation

Run the installer command to configure settings interactively:

One-Line Non-Interactive Installation

You can pass configuration options directly in a single non-interactive command (ideal for automated setup scripts or CI/CD):

Options Supported:

• --key=: Set the project API key (LARASIGNAL_KEY). Updates .env even if skipped.
• --sample-rate=: Telemetry sampling rate (LARASIGNAL_SAMPLE_RATE, e.g. 0.5 for 50%).
• --record-queries=: Enable/disable database query collection (LARASIGNAL_RECORD_QUERIES=true|false).
• --ingest-url=: Custom ingestion endpoint (LARASIGNAL_INGEST_URL). Default: https://larasignal.com/api/v1/ingest/batches.

Delivery Modes & Minimizing Response Latency

LaraSignal is designed to minimize latency impact on user HTTP responses. You can choose between two delivery strategies:

1. End-of-Lifecycle Asynchronous Flushing (Default, LARASIGNAL_ASYNC=false): Telemetry spans are buffered in memory and flushed asynchronously at the end of the HTTP request or queue job lifecycle (app()->terminating()) after the HTTP response has already been sent to the browser.

2. Background Batch Dispatcher (LARASIGNAL_ASYNC=true + php artisan larasignal:run): Telemetry payloads are written directly to local disk spooling (storage/app/larasignal/spool) in 0ms and processed by a background worker process, completely isolating user HTTP responses from network ingestion latency.

Run the background worker daemon:

Verification & CLI Tools

• php artisan larasignal:status: Inspect current configuration and API key health.
• php artisan larasignal:test: Dispatch a test telemetry event to verify ingestion.
• php artisan larasignal:deployment v1.2.0: Record a deployment release event in LaraSignal.
• php artisan larasignal:flush: Re-send offline spooled telemetry batches.
• php artisan larasignal:run: Start the background telemetry worker process.
• php artisan larasignal:help: Display CLI help summary and environment variable reference.

Features & Programmatic API

1. Custom Events & Code Execution Measurement

2. Global Context & Tagging

3. User Identification

Authenticated users (Auth::user()) are automatically captured (sanitized user ID & email). You can also explicitly associate a user:

4. Automatic Log Ingestion

Laravel logs (Log::info(), Log::warning(), Log::error()) are automatically captured as telemetry log spans with log level and context metadata (configurable via LARASIGNAL_RECORD_LOGS=true).

5. Storage, Runtime & Provider Metrics

Measure filesystem operations without transmitting object paths:

Report application or worker health gauges and provider-supplied WebSocket totals:

Schedule php artisan larasignal:heartbeat scheduler --every=60 at the same interval to surface healthy and missed scheduler heartbeats in Runtime health.

Authentication, authorization denials, throttled requests, queue health, database transactions, cache outcomes, HTTP connection failures, deployments, spans, and Laravel worker lifecycle events are captured automatically.