Capture real-world query patterns safely

Development performance testing has a fundamental problem: your local database has 100 records and 1 concurrent user. Production has 100,000 records and 500 concurrent users. The performance characteristics are completely different.

Query plans change based on data volume. What uses an index locally might sequential scan in production because the planner thinks it's cheaper. What runs in 10ms locally might take 10 seconds with real data. Production captures reveal these issues before they become user-facing outages.

The safety design reflects lessons learned from production monitoring tools that caused more problems than they solved. We've all seen monitoring systems that consume 30% of CPU just to tell you the CPU is busy. laraperf takes a different approach: do the minimum work necessary, do it asynchronously, and always prioritize application availability over data completeness.

If disk space runs low, the capture degrades gracefully—it might miss some queries, but it won't crash your app. If the JSON file grows large, rotation happens automatically. These failure modes are designed to be safe by default.

The --tag flag is invaluable for organizing captures. You might run --tag=checkout-flow when testing the checkout process, or --tag=monday-morning to capture peak traffic patterns. When you run perf:query --session=last, the tag shows up in the metadata so you remember what you were investigating.

The detached mode is the default because you typically want to exercise the app while capturing. You might run your test suite, click through the UI manually, or run a load test. The capture continues in the background regardless of what you're doing in the foreground.

Capture when:

You have a specific performance issue to investigate (slow page load, timeout reports). You're deploying a change and want to verify no regression. Users report intermittent slowness you can't reproduce locally. You want to establish a performance baseline before major changes.

Avoid capturing when:

The system is already under stress—capture adds load, even if minimal. You're running bulk operations that aren't representative like one-time imports or migrations. Database is in recovery or backup mode with unusual performance characteristics. You haven't tested the overhead in a non-production environment first.

The most valuable production captures are often the ones you run when investigating specific issues. A user reports "the report page is slow between 9-10 AM." You SSH in at 9:05, run perf:watch --seconds=600, and capture exactly what's happening during the problem window.

This targeted approach is more valuable than continuous monitoring because it captures the specific conditions causing problems. You see the query plans that execute slowly, the N+1 patterns that emerge under load, and the exact line numbers in your code where optimizations will have the most impact.

Multi-tenant applications have unique debugging challenges. A query that's fast for tenant A might be slow for tenant B due to different data volumes or distributions. The --db flag lets you investigate specific tenant issues without switching connection configurations.

This is particularly useful for support scenarios. A tenant reports slowness on a specific feature. You can capture their specific database, analyze their specific query patterns, and give them specific optimization advice rather than generic best practices.

There's no automatic cleanup because we believe in explicit data management. Your query history might be valuable for trend analysis, and we don't want to delete data you might need. But sessions do accumulate—especially if you're doing frequent captures during debugging—so periodic cleanup is recommended.

The --force flag skips the confirmation prompt, making it suitable for cron jobs. A weekly 0 0 * * 0 cd /var/www && php artisan perf:clear --force keeps storage clean without manual intervention.