Laravel SDK Quickstart

1Install via Composer

The service provider and Beacon facade are auto-discovered — no manual registration needed:

2Configure Your API Key

Add these to your .env file:

BEACON_INGEST_URL=https://beacon-api.trustportidentity.com
BEACON_API_KEY=tb_live_your_tenant_key
BEACON_SERVICE_NAME=billing-api
BEACON_ENVIRONMENT=production   # label in Beacon: production / staging / local
BEACON_SAMPLE_RATE=1            # 0-1; errors are always sent

3Request Tracing (automatic)

Nothing to do: the package adds BeaconMiddleware to the global stack itself once BEACON_API_KEY is set. Health checks (up, health, api/health) are skipped; change with BEACON_IGNORE_PATHS. Only if you set BEACON_AUTO_MIDDLEWARE=false do you register it yourself:

use TrustPortIdentity\Beacon\BeaconMiddleware;

protected $middleware = [
    BeaconMiddleware::class,
    // ...your other global middleware
];

4Custom Spans with the Beacon Facade

use TrustPortIdentity\Beacon\Beacon;

class InvoiceController extends Controller
{
    public function index()
    {
        $span = Beacon::span('db.mysql.select_invoices', 'database');
        $invoices = Invoice::where('status', 'pending')->get();
        $span->setTag('rows', $invoices->count())->end();

        Beacon::identify(['id' => auth()->id(), 'email' => auth()->user()?->email]);

        return response()->json($invoices);
    }
}

5Queue Job Tracking

6Control Ingest Volume with BEACON_SAMPLE_RATE

Every request is already batched (BEACON_BATCH_SIZE) instead of one network call per request. On top of that, set BEACON_SAMPLE_RATE (0.0–1.0, default 1.0) to trace only a fraction of requests in high-traffic services — this is what actually keeps you inside your plan's monthly quota. Exceptions are always sent regardless of sampling.

BEACON_SAMPLE_RATE=0.2  # trace ~20% of requests

What errors are captured

Opt out with BEACON_CAPTURE_EXCEPTIONS=false or BEACON_CAPTURE_FATALS=false.

Privacy: what is always redacted

No setting needed. The Authorization, Cookie, Set-Cookie, X-Api-Key and CSRF headers are replaced with [redacted], and so is the value of any query parameter that looks like a secret (token, secret, password, auth, signature, session, key, cron_key, api_key). Beacon's server scrubs the same names again on ingest. BEACON_SANITIZE_PII=true also removes card-number-like values.

Migrating from Laravel Nightwatch

1. Stop the agent: php artisan nightwatch:agent (Beacon has no agent process; remove its supervisor program).
2. composer remove laravel/nightwatch, then install Beacon as above.
3. Replace NIGHTWATCH_TOKEN / NIGHTWATCH_REQUEST_SAMPLE_RATE with BEACON_API_KEY / BEACON_SAMPLE_RATE.
4. php artisan config:clear and php artisan queue:restart.

Troubleshooting

• Only a few requests show up: BEACON_SAMPLE_RATE is below 1, or the path is in BEACON_IGNORE_PATHS (supports *, e.g. api/send_*_mails for cron pings).
• Nothing shows up: BEACON_API_KEY unset, config cached (php artisan config:clear), or the server cannot reach BEACON_INGEST_URL.
• Requests have no user: the app authenticates in a way Laravel's guards do not see; call Beacon::identify([...]).
• Config changes ignored in workers: run php artisan queue:restart.