Laralyze Laravel Package

Getting Started

Laralyze is a self-hosted observability dashboard: it records request, job, query, exception, log, cache, AI, and outbound HTTP activity into a store you control, then renders it in a Laravel-served UI. Treat it as "Telescope/Horizon, but with a dashboard you own and a ClickHouse option for volume."

1. Check requirements first. The package targets modern Laravel (10/11+) and PHP 8.1+. You need a database for the metadata store; ClickHouse is optional but only worth it if you expect high write volume. Confirm the exact supported matrix in the repo's README before installing — this is a young package (30 stars), so version constraints move.
2. Install and publish.

   composer require mohammed-mojaly/laralyze
   php artisan vendor:publish --tag=laralyze-config   # name may differ; check the provider
   php artisan migrate
   

   If the package ships an install command (e.g. php artisan laralyze:install), prefer it — it typically publishes config, migrations, and the dashboard assets in one pass.
3. Set the minimum env. Expect something along the lines of:

   LARALYZE_ENABLED=true
   LARALYZE_DRIVER=database      # or clickhouse
   LARALYZE_PATH=laralyze        # dashboard route prefix
   # ClickHouse driver:
   LARALYZE_CLICKHOUSE_HOST=...
   LARALYZE_CLICKHOUSE_DATABASE=laralyze
   

4. Where to look first.
   • config/laralyze.php — driver, sampling rate, retention, redaction/ignore lists, watcher toggles. This file is the whole product surface.
   • The service provider / event listeners — this is where requests, jobs, queries, and exceptions are hooked. Read it once; it tells you exactly what is and isn't captured.
   • The dashboard routes and their middleware — you will need to gate these.
5. First use case. Enable it locally at 100% sampling, load one page of your app, then open the corresponding request entry in the dashboard. Walk the timeline: queries with timings and bindings, cache hits/misses, outbound HTTP calls, log lines, and any exception attached to that request. That single trace is the fastest way to validate the install and understand the data model.

Implementation Patterns

Driver selection as a scaling decision, not a preference.

• database driver: fine for local, staging, and small production apps. Point it at a separate connection so ingestion doesn't compete with your app's primary queries.
• clickhouse driver: use when you're writing more than a few hundred thousand records a day or need fast range queries over weeks of data. Budget for running ClickHouse itself (container or managed) and for a second migration path — the package's migrations for ClickHouse are typically run through its own command, not php artisan migrate.

Sampling per environment.

// config/laralyze.php
'sampling' => [
    'requests' => env('LARALYZE_SAMPLE_REQUESTS', 1.0),
    'queries'  => env('LARALYZE_SAMPLE_QUERIES', 0.1),
],

Keep local at 1.0, production requests at 0.05–0.2, and queries lower still. Queries are the highest-volume signal by an order of magnitude.

Queue the write path. If the config exposes an async/buffered ingestion mode, turn it on in production. Synchronous inserts add latency to every request and turn a database hiccup into an application outage. Pair it with a flush on terminate so the last records of a request survive.

Context propagation is your job. The dashboard is only useful when you can answer "which user, which tenant, which job?" Attach context in a middleware (user ID, tenant ID, request ID) and ensure queue workers re-establish it per job. In Octane or long-running Horizon workers, state left over from a previous job will otherwise bleed into the next one's trace — reset context at the start of each job.

Custom instrumentation. If the package exposes a facade or helper for manual spans, wrap it in your own thin service class rather than calling it from dozens of places. That gives you a single place to no-op it when the package's API changes, and a single place to enforce redaction.

Alerting on top of the dashboard. A dashboard nobody opens is decoration. Wire the exception and slow-query thresholds into your existing alerting (Slack/webhook) so the dashboard becomes the drill-down after the page, not the detection mechanism.

Retention as a scheduled concern. Configure a retention window and confirm the prune command is actually scheduled in routes/console.php or the scheduler. Unpruned observability tables are a classic way to fill a disk quietly.

Gotchas and Tips

• Sensitive data leakage is the default failure mode. SQL bindings, request bodies, headers, AI prompts, and log context routinely contain passwords, tokens, and PII. Configure the redaction/ignore lists before enabling in production, and test with a request that carries a fake bearer token.
• The dashboard is an unauthenticated route until you make it otherwise. Apply your auth middleware and a gate/ability check to the route prefix. Never expose it on a public host without that. In production, consider IP allowlisting or a separate internal hostname.
• Separate database connection. If the database driver writes to your primary connection, you're adding writes to the same pool serving users. Use a dedicated connection and, ideally, a dedicated schema.
• Migration footprint. The package adds tables to your database. On large existing databases, review the migration before running it in production; on ClickHouse, use the package's own migration path.
• Async buffers lose the tail. Buffered ingestion means the records leading up to a fatal error (OOM, segfault) may never flush. Don't rely on Laralyze as your only crash forensics — keep file logs.
• Sampling distorts percentiles. At a 5% request sample, a p99 on 20 requests is noise. Read sampled metrics as trends, not SLAs.
• Long-running processes and static state. Under Octane, Horizon, or Swoole, listeners and buffers persist across requests/jobs. Anything the package stores in a singleton must be reset per unit of work; verify this yourself with two sequential jobs and inspect whether context leaked.
• Disable it in tests. Add the package to your phpunit.xml env exclusions (LARALYZE_ENABLED=false) or you'll pay migration and ingestion costs on every test run and pollute your traces.
• Pin the version. At this maturity level, expect breaking changes between minors. Pin in composer.json, read the changelog before upgrading, and keep any custom instrumentation behind your own wrapper.
• Timezones. Ingestion timestamps and your application's display timezone can diverge, which makes correlating a Laralyze trace against an application log line frustrating. Store UTC and convert at the dashboard.
• When something isn't recorded, debug in this order: is LARALYZE_ENABLED true in that environment → is the relevant watcher toggled in config → did the queue worker pick up a stale config (restart workers after config changes) → is sampling set to 0 → is the redaction/ignore list swallowing the record.