Connect a Laravel app

The lampwick/laravel package sends requests, queries, jobs, exceptions, logs and more from your Laravel app to Lampwick. Your app hands its records to an agent on the same server at 127.0.0.1:2407, so requests never wait on the network. The agent sends them in batches to https://app.lampwick.dev/ingest. While Lampwick is unreachable, it keeps up to 64 MB of records in memory and retries.

Requirements

PHP 8.2 or later with the curl extension.
Laravel 12 or 13.
Optional: the pcntl extension, so the agent sends its buffer when it stops.
The project's ingest token, from its Settings page. Only team owners see it.

Install the package

Add the package:
```
composer require lampwick/laravel
```
Add the ingest token to .env:
```
LAMPWICK_TOKEN=YOUR_PROJECT_TOKEN
```
YOUR_PROJECT_TOKEN is the ingest token from the Connect your app card on the project's Settings page.
Optional: to send your application logs, add the lampwick channel to your log stack:
```
LOG_STACK=single,lampwick
```
Start the agent:
```
php artisan lampwick:agent
```

Check that it works

In a second terminal, run:

php artisan lampwick:test

It sends a test log record straight to Lampwick, to check your token and network, and checks that the agent runs. Then open your app: the request shows up in Lampwick within seconds.

Keep the agent running in production

Run one agent per server under a process manager, like a queue worker. Restart it after each deploy: it reads .env and the config only when it starts.

Laravel Forge

Go to your server → Daemons → New daemon:

Field	Value
Command	`php artisan lampwick:agent`
Directory	your site's directory, for example `/home/forge/example.com/current`
User	`forge`
Stop wait seconds	`15`

Supervisor

[program:lampwick-agent]
command=php /var/www/example.com/artisan lampwick:agent
directory=/var/www/example.com
user=www-data
autostart=true
autorestart=true
stopsignal=TERM
stopwaitsecs=15
redirect_stderr=true
stdout_logfile=/var/log/lampwick-agent.log

Replace /var/www/example.com and www-data with your app's directory and PHP user, then load the program:

sudo supervisorctl reread && sudo supervisorctl update

On SIGTERM the agent stops taking records, sends what it has buffered and exits within LAMPWICK_AGENT_SHUTDOWN_TIMEOUT seconds (10 by default). Keep stopwaitsecs above that.

Docker and multiple servers

Every server or container that runs PHP needs an agent it can reach. Run it in the same container, or as a sidecar with LAMPWICK_AGENT_LISTEN set to 0.0.0.0:2407 for the agent and agent:2407 for the app. Never expose the agent's port to the internet: it accepts data from anyone who can reach it.

Configuration

Set everything with environment variables, or publish the config file with php artisan vendor:publish --tag=lampwick-config.

Variable	Default	What it does
`LAMPWICK_TOKEN`	none	The project's ingest token. Without it nothing is captured.
`LAMPWICK_ENABLED`	`true`	`false` turns the instrumentation off.
`LAMPWICK_AGENT_LISTEN`	`127.0.0.1:2407`	Address the agent listens on and the app sends to.
`LAMPWICK_AGENT_SHUTDOWN_TIMEOUT`	`10`	Seconds the agent takes to send its buffer when it stops.
`LAMPWICK_SERVER`	hostname	Server name shown in Lampwick.
`LAMPWICK_DEPLOY`	Forge, Vapor or Cloud commit	Deployment identifier.
`LAMPWICK_REQUEST_SAMPLE_RATE`	`1.0`	Share of requests to capture, from 0.0 to 1.0.
`LAMPWICK_SCHEDULED_TASK_SAMPLE_RATE`	`1.0`	Same, for scheduled tasks. Keep it at 1: alerts about missed runs need every run.
`LAMPWICK_IGNORE_QUERIES`	`false`	Don't capture database queries.
`LAMPWICK_IGNORE_CACHE_EVENTS`	`false`	Don't capture cache hits, misses and writes.
`LAMPWICK_LOG_LEVEL`	`LOG_LEVEL`	Lowest log level sent through the `lampwick` channel.
`LAMPWICK_CAPTURE_REQUEST_PAYLOAD`	`false`	Include request bodies, with the fields below redacted.
`LAMPWICK_REDACT_PAYLOAD_FIELDS`	`_token,password,password_confirmation`	Comma-separated.
`LAMPWICK_REDACT_HEADERS`	`Authorization,Cookie,Proxy-Authorization,X-XSRF-TOKEN`	Comma-separated.

The package's README lists every variable.

Troubleshooting

What you see	Cause and fix
Nothing shows up in Lampwick	Run `php artisan lampwick:test`. Check that the agent runs with the same `.env` as the app, and that `LAMPWICK_TOKEN` is set for both.
`address already in use`	Another agent already listens on that port. Stop it, or pick another `LAMPWICK_AGENT_LISTEN` (the app and the agent read the same setting).
`HTTP 401` in the agent's log	The token is wrong or the project was deleted. Copy it again from the project's Settings page.
A changed `.env` has no effect	The config is cached. Run `php artisan config:cache` again and restart the agent.
Two apps on one server mix up	They can't: the agent refuses payloads with another token. Give each app its own `LAMPWICK_AGENT_LISTEN` port.