README

A lightweight, HTTP-focused observability package for Laravel. Beacon records every incoming HTTP request and every outgoing HTTP call, along with the queries, model events, and queued jobs they triggered, and serves them through a built-in Vue dashboard.

It is intentionally narrower than Laravel Telescope — only the parts most teams care about in production: HTTP traffic and the work that traffic kicked off.

Contents

• Why Beacon?
• Features
• Beacon vs Telescope
• Requirements
• Installation
• Configuration
• Artisan Commands
• Authentication
• Sharing Requests
• Testing
• Screenshots
• License

Why Beacon?

• HTTP-first. No watchers for things you rarely need in production (mail, cache, redis, views, dumps, ...). Just requests in, requests out, and what they did.
• Filterable at scale. Beacon stores queries, model touches, and job dispatches in normalized tables with composite indexes.
• Caller everywhere. Each captured query, model event, and dispatched job is tagged with the user-code call site (e.g. App\Services\UserService@updateUser:14), not just queries.
• Modern stack. Vue 3, Vite, Tailwind v4. Compiled assets ship with the package — no Node toolchain required in the consumer app.

Features

• Incoming HTTP request capture (method, path, status, duration, memory, IP, headers, payload, response, controller action, middleware)
• Outgoing HTTP request capture (method, URI, status, duration, headers, payload, response, error)
• Per-request rollups: queries (with bindings), model touches (with diff), dispatched jobs (with payload)
• Caller stack capture for queries, models, jobs, and outgoing HTTP calls — Class@method:line
• Header and parameter redaction (case-insensitive headers, dot/wildcard parameter paths)
• Search + method + status-range + date-range + duration + failed-only filters (date range is timezone-aware — browser local → UTC)
• Wildcard search — use * in the search term, e.g. */chat/*
• Sort lists by id or duration, ascending or descending
• Auto-refresh lists on a 5s interval with a live countdown (toggle remembered per list)
• Copy as cURL — reconstruct any captured request as a curl command from its detail view
• Share a request — generate a link to any captured request, with an optional password and expiry; revoke it anytime. Shared links open for recipients with no Beacon access
• Keyset pagination (?before_id=N)
• Pause / resume recording from the UI or via Artisan
• Bulk delete from the UI
• Retention pruning command (chunked DELETE)
• Hard row caps (incoming.max_rows / outgoing.max_rows) — oldest entries auto-trim FIFO with concurrency-safe locking
• Configurable route middleware — drop in your own auth gate via beacon.middleware
• Configurable sampling rate, body size limits, ignored hosts/paths/methods/status codes
• Dashboard with selectable time windows (Last One Hour / Today / Yesterday / This Week / This Month / Last Week / Last Month): counts, incoming + outgoing status buckets, slowest endpoints, failed outgoing
• Top navigation bar; list rows show relative + absolute (local & UTC) timestamps
• UI assets served straight from vendor/ — composer update ships new bundles, no vendor:publish follow-up

Beacon vs Telescope

If you need a kitchen-sink debug tool in development, Telescope is the better fit. If you want production-grade HTTP traffic observability with fast filtering and predictable storage, use Beacon.

Requirements

• PHP 8.1+
• Laravel 10, 11, 12, or 13
• MySQL, Postgres, or SQLite

Installation

composer require tintaungkhant/laravel-http-beacon

Run the install command — it publishes the config and the migrations, then run the migration:

php artisan beacon:install
php artisan migrate

Open /beacon in your browser. UI assets are served by the package itself — no vendor:publish --tag=beacon-assets step. composer update is the only thing you need to run when a new version ships, and the bundle URL carries a cache-buster so browsers pick up the new build automatically.

Configuration

After install, the config lives at config/beacon.php. The most-used keys:

return [
    'enabled' => env('BEACON_ENABLED', true),

    'storage' => [
        'connection' => env('DB_CONNECTION', 'mysql'),
    ],

    'sampling_rate' => (float) env('BEACON_SAMPLING_RATE', 1.0), // 0.1 = 10% of traffic

    // Middleware applied to every Beacon route (dashboard view + JSON API).
    // Add an auth gate here, e.g. ['web', 'auth', 'can:viewBeacon'].
    'middleware' => ['web'],

    // Request sharing — set enabled to false to remove the share routes and
    // hide the share UI. Shared links are intentionally ungated.
    'sharing' => [
        'enabled' => (bool) env('BEACON_SHARING_ENABLED', true),
    ],

    'redact' => (bool) env('BEACON_REDACT', true),

    'hidden_headers' => [
        'authorization', 'cookie', 'set-cookie', 'x-api-key', 'x-csrf-token',
    ],

    'hidden_parameters' => [
        'password', 'password_confirmation', 'token', 'secret', '_token',
    ],

    'incoming' => [
        'enabled' => true,
        'body_size_limit_kb' => 64,
        'max_rows' => null,            // null/0 = unlimited; otherwise oldest rows are auto-trimmed FIFO
        'only_paths' => [],            // ['api/*'] to record only API routes
        'ignore_paths' => ['beacon*', 'horizon*', 'telescope*', '_ignition*'],
        'ignore_methods' => [],
        'ignore_status_codes' => [],
    ],

    'outgoing' => [
        'enabled' => true,
        'body_size_limit_kb' => 64,
        'max_rows' => null,            // null/0 = unlimited; same FIFO trim behavior
        'ignore_hosts' => [],          // ['*.amazonaws.com']
    ],

    'collect' => [
        'queries' => true,
        'models' => true,
        'jobs' => true,
        'memory' => true,
        'model_actions' => ['created', 'updated', 'deleted', 'restored', 'retrieved'],
        'max_queries_per_request' => null, // 0 / null = unlimited
    ],

    'retention' => [
        'hours' => (int) env('BEACON_RETENTION_HOURS', 168), // 7 days
        'chunk_size' => 1000,
    ],
];

Hidden parameter paths support dot notation and wildcards: user.password, tokens.*.value.

Artisan Commands

php artisan beacon:install   # publish config + migrations + assets, then migrate
php artisan beacon:pause     # stop recording (cache flag, persists across requests)
php artisan beacon:resume    # resume recording
php artisan beacon:clear     # truncate beacon_incoming_requests + beacon_outgoing_requests
php artisan beacon:prune     # delete entries older than retention.hours
php artisan beacon:prune --hours=24      # override retention
php artisan beacon:prune --dry-run       # count without deleting

The same pause / resume / clear actions are available from the dashboard header.

Schedule pruning with your application's scheduler:

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('beacon:prune')->daily();

Authentication

Beacon defaults to 'middleware' => ['web'], which gives you sessions and CSRF but no auth gate. For production, add your own gate via the same config key:

// config/beacon.php
'middleware' => ['web', 'auth', 'can:viewBeacon'],

…and define the gate however you normally would:

// app/Providers/AppServiceProvider.php
Gate::define('viewBeacon', fn ($user) => in_array($user->email, ['ops@example.com']));

Or just disable Beacon entirely in production:

# .env
BEACON_ENABLED=false

A built-in gate is on the roadmap.

Sharing Requests

Any captured request can be shared from its detail view. Hit Share, pick an expiry (1 hour up to 30 days, or never) and an optional password, and Beacon returns a link.

Shared links are deliberately ungated — they open for anyone who has the link, even without Beacon access — so the token, password, and expiry are the protection. Passwords are stored hashed; the shared view serves the same already-redacted data as the in-app detail. Manage and revoke every link from the Shared tab.

Set beacon.sharing.enabled to false (or BEACON_SHARING_ENABLED=false) to remove the feature entirely. beacon:clear drops shared links along with the traffic; beacon:prune also clears revoked and expired links.

Sharing adds one migration (beacon_shared_links). After composer update, run php artisan vendor:publish --tag=beacon-migrations (or beacon:install) and php artisan migrate.

Testing

composer install
composer test       # phpunit
vendor/bin/phpstan  # level 5 with larastan

Screenshots

Dashboard

Aggregation over a selectable time window: incoming + outgoing volumes, failure counts, incoming and outgoing status breakdowns, and the slowest endpoints (clickable through to detail).

Incoming Requests

List view with wildcard search, method / status / date-range / duration filters, sort, and an auto-refresh toggle with countdown. Each row carries relative, local, and UTC timestamps. Pause / resume / delete-all in the header.

Incoming Request Detail

Attributes, request payload, headers, and response — plus the queries / models / jobs that ran during the request, each tagged with the user-code caller. Share and Copy as cURL from the header.

Outgoing Requests

List view with the Failed only toggle for connection errors — same search, sort, filters, and auto-refresh as the incoming list.

Outgoing Request Detail

URI, status, duration, and the caller call site, plus request payload, headers, and response — same redaction rules as incoming.

Sharing

Generate a shareable link to any captured request from its detail view, with an optional password and expiry.

The Shared page lists every link with its status, view count, and last-viewed time — and revokes any of them.

License

The MIT License (MIT). See LICENSE.