serverfy / sense
Serverfy Sense - Zero-overhead Deep APM, Waterfall Tracing, Error Tracking and SRE bridge for Laravel
Requires
- php: ^8.1|^8.2|^8.3|^8.4
- illuminate/database: ^10.0|^11.0|^12.0|^13.0
- illuminate/http: ^10.0|^11.0|^12.0|^13.0
- illuminate/support: ^10.0|^11.0|^12.0|^13.0
- monolog/monolog: ^3.0
Requires (Dev)
- orchestra/testbench: ^8.0|^9.0|^10.0|^11.0
- pestphp/pest: ^2.0|^3.0|^4.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Serverfy Sense records errors, request traces, queries, queued jobs and scheduled tasks of a Laravel 10, 11, 12 or 13 application and sends them to your Serverfy console.
📦 Installation
Install the package via Composer:
composer require serverfy/sense
Optionally publish the configuration file:
php artisan vendor:publish --tag="sense-config"
⚙️ Configuration
Add the DSN of your site (Serverfy console, Site > Sense > Setup) to .env:
SERVERFY_SENSE_DSN="https://your-serverfy-host/api/v1/telemetry?key=sfy_live_your_site_key"
That is the whole setup. Optional settings:
SERVERFY_SENSE_SAMPLE_RATE=0.2 # store one in five traces; failures are always stored SERVERFY_SENSE_RELEASE="${GIT_COMMIT}" # label errors with the deploy they came from SERVERFY_SENSE_ENVIRONMENT=production SERVERFY_SENSE_SEND_REQUEST_BODY=false # request bodies are not sent unless you opt in
🧪 Testing Connectivity
php artisan sense:test
📖 What is recorded
Once the DSN is set, with no code changes:
| What | How it shows up |
|---|---|
| HTTP requests | One trace per request, named after the route pattern (GET /orders/{order}) |
| Database queries | Spans inside the trace; slow queries are also reported outside of traces |
| Queued jobs | One trace per job, linked to the request that dispatched it |
| Artisan commands and scheduled tasks | One trace each (long-running workers are skipped) |
| Cache reads and writes, outgoing HTTP calls | Spans inside the current trace |
| Reported exceptions | Stack trace, source lines around the failure, request and user id |
Telemetry is collected in memory and sent in one compressed batch after the response has gone out, so a request never waits for it. A failure to deliver is silent and never reaches your application.
Privacy
Values of keys that look like credentials (password, token, secret, authorization,
cookie, card data) are replaced before anything leaves the server, SQL is sent with its
placeholders and never with bound values, outgoing HTTP calls are recorded without their query
string, and request bodies are only sent when you opt in.
Sampling
SERVERFY_SENSE_SAMPLE_RATE controls how many traces are stored in full. Failed requests and
jobs are always sent, and every sampled trace carries the weight of the ones left out, so
request counts, error rates and percentiles in Sense stay accurate.
Application logs
// config/logging.php 'sense' => [ 'driver' => 'monolog', 'handler' => \Serverfy\Sense\Logging\SenseMonologHandler::class, 'level' => 'warning', ],
LOG_STACK=single,sense
Local agent (optional)
On a busy site, run the agent next to the application and telemetry stops costing a network call per request: the application hands it over a local socket and the agent forwards everything in batches.
php artisan sense:agent
Keep it running with Supervisor or systemd, as the same user that runs the application. No
configuration is needed: the SDK finds the agent on storage/framework/sense.sock and falls
back to sending directly whenever the agent is not there. php artisan sense:agent --ping
tells you whether it is up.
Your own metrics
use Serverfy\Sense\Facades\Sense; Sense::metric('orders.paid'); // count something Sense::metric('checkout.total_cents', 15990); // or measure it
Sense keeps the count, total, average and percentiles of each metric per minute. They show up in the performance tab, and an alert rule can watch them ("tell me when fewer than 5 orders are paid in 30 minutes"). Keep names stable and never put ids in them.
Manual capture
use Serverfy\Sense\Facades\Sense; use Serverfy\Sense\Tracing\TraceRecorder; // An exception you caught yourself Sense::captureException($e, ['user' => ['id' => auth()->id()]]); // Time a block of code as a span of the current trace app(TraceRecorder::class)->measure('render invoice pdf', fn () => $pdf->render());
🛡️ License
The MIT License (MIT). Please see License File for more information.