eyewitness/eye
Eyewitness Eye is a lightweight, self-hosted Laravel package that keeps watch over your application, capturing errors and exceptions and presenting them in a clean, searchable dashboard so you can diagnose issues quickly and keep your app healthy.
The package is a thin Laravel 5 client that pushes application telemetry (requests, exceptions, queue jobs, custom events) to the hosted Eyewitness.io service — there is no dashboard, storage, or self-hosted component inside the package itself. Before investing time, confirm two things: first, that the Eyewitness.io service is still reachable (it was a small SaaS that has historically gone dark), and second, that your Laravel version is in the supported 5.x range — this package targets Laravel 5 and will not work cleanly on 6+, and definitely not on 9/10/11.
Minimal setup:
composer require eyewitness/eyephp artisan vendor:publish --provider="Eyewitness\Eye\EyeServiceProvider".env (typically EYEWITNESS_API_KEY and EYEWITNESS_APP_NAME)config/app.php under providers if you're on Laravel < 5.5 (5.5+ auto-discovers via composer.json)app/Http/Kernel.php — it must run after StartSession and before SubstituteBindings if you care about user context on captured requestsFirst use case: wire up exception capture. Extend your App\Exceptions\Handler::report() to call the Eyewitness client in addition to parent::report($e). This gives you the fastest value for the least integration effort — everything else (request timing, queue telemetry) is incremental. Do this on a single staging app, hit it with a deliberate throw new \Exception('test'), and confirm it lands on the hosted dashboard before rolling out to production.
Where to look first in the repo: src/EyeServiceProvider.php (what's registered), src/Config/ (which config keys exist — this is your integration surface), and src/Facades/Eye.php (public API for custom tracking).
Middleware-based request tracking. The canonical usage is to push the package's middleware onto the web (and optionally api) group. It wraps the request, records timing, status, and selected request metadata, and flushes a payload on the way out. Treat it as fire-and-forget — it should never block the response. If you see slow php artisan serve behaviour after install, the client is likely making synchronous HTTP calls in the terminate phase; move the flush to a queued listener or accept the latency hit only on your slowest routes.
Exception handler integration. The most valuable integration point. In Handler::report():
public function report(Exception $e)
{
if (app()->bound('eyewitness') && $this->shouldReport($e)) {
app('eyewitness')->captureException($e);
}
parent::report($e);
}
Gate on shouldReport() so you don't ship duplicate noise for exceptions your $dontReport list already silences.
Custom event tracking. Use the facade for business-level signals — "checkout completed", "webhook received", "import row X failed". Prefer a small, stable vocabulary of event names over free-form strings; the hosted dashboard's grouping is only useful if names are consistent. Wrap the call site in a helper service so you can swap the backend later without touching fifty call sites.
Queue and scheduler instrumentation. If the package exposes queue listeners, they typically register via Illuminate\Queue\Events\* — usually automatic through the service provider. The valuable config knob here is the "queue/job whitelist": you rarely want every job tracked, only the scheduled ones and the slow ones. Scheduler tracking usually piggybacks on the artisan command listener; confirm in the config whether heartbeats are sent automatically or require an explicit ->tracked() call in Kernel::schedule().
Environment gating. Common pattern in these clients: enabled/disabled per environment. Wire it up so production and staging report, and local/testing do not. Use a wrapper class rather than null-guarding everywhere:
class Telemetry
{
public function event(string $name, array $data = []): void
{
if (!config('eyewitness.enabled')) return;
app('eyewitness')->event($name, $data);
}
}
Then inject Telemetry everywhere — no facade, no app()->bound() checks scattered across domain code.
User context. If the middleware captures the authenticated user, redact PII in the config (eyewitness.user.exclude or similar) before it leaves your app. In a health/HR/fintech context this is non-negotiable and there is no server-side redaction you can rely on.
Sampling. For high-traffic APIs, configure a sampling rate in config/eyewitness.php if the option exists. A 5–10% sample is usually enough for latency/error-rate signals and avoids both cost and payload overhead.
curl the ingest endpoint with a dummy key. If it doesn't respond, this is a dead-end and you should pivot to Sentry, Flare, or a roll-your-own solution — the integration surface here is small enough that the swap cost is negligible.Class 'Eyewitness\Eye\EyeServiceProvider' not found on boot, you forgot to add it to config/app.php.terminate(). Behind a load balancer with short timeouts this can produce 500s on your own app when Eyewitness is slow. Always set a short timeout (2–3s) in the config, and never let failures from the client bubble — wrap calls with try/catch that logs and swallows.config:cache will bite you. Any env-driven config inside the package (API key, endpoint URL) must be read through config(), not env(). If the package's source uses env() directly, it will silently return null in production after caching. Sanity-check by running php artisan config:cache locally and confirming payloads still reach the endpoint.StartSession you lose user context; placed after SubstituteBindings you lose route-model data. Standard slot is right after StartSession. On API routes, if you're using Sanctum/Passport, verify user capture works — many older packages only checked Auth::user() which may be null under stateless auth.APP_DEBUG=true; otherwise when payloads stop landing you have zero visibility. Check storage/logs/laravel.log for cURL errors, and watch php artisan queue:work output if the client dispatches queued reporting jobs.Telemetry interface in front and implement it twice — far cheaper than fighting the package's internals.composer.json ("eyewitness/eye": "1.x.x", not ^1.0) so a maintainer commit can't surprise you in CI.login, password/*, oauth/* routes if the config allows; otherwise file a wrapper that no-ops on those paths.How can I help you explore Laravel packages today?