Download the PHP package ahmedmashhour/laravel-query-debugger without Composer

Laravel Query Debugger

Automatic query tracking, analysis, and debugging for Laravel applications with N+1 detection, slow query monitoring, and performance insights.

Features

• ✅ Auto-Tracking: Automatically track all database queries with zero code changes
• ✅ Daily JSON Logs: Store queries in JSON format with daily rotation
• ✅ N+1 Detection: Automatically detect and alert on N+1 query patterns
• ✅ Slow Query Monitoring: Flag queries exceeding configurable thresholds
• ✅ EXPLAIN ANALYZE: Auto-execute EXPLAIN for slow queries
• ✅ Backtrace Collection: Track where queries originate in your code
• ✅ API Response Injection: Optionally include query debug data in responses
• ✅ Multi-Tenant Support: Optional tenant context capture
• ✅ Sampling: Reduce overhead by sampling percentage of queries
• ✅ Alert System: Log, Slack notifications for query issues
• ✅ Per-Route Configuration: Different settings per endpoint
• ✅ Artisan Commands: Analyze and clean logs via CLI

Installation

Option 1: Install from GitHub (Recommended)

Add the package repository to your composer.json:

Then install via Composer:

Or specify a specific version/tag:

Option 2: Install from Local Path

Add the package to your composer.json:

Run composer install:

Step 2: Publish Configuration (Optional)

Step 3: Configure

Add to your .env:

Configuration

Quick Start - Key Environment Variables

Basic Settings

Storage

N+1 Detection

API Response Injection

Alerts

Usage

Enable for Development

Enable for Specific Request

Summary Response (default - QUERY_DEBUG_FULL_QUERIES_IN_RESPONSE=false):

Full Response (with QUERY_DEBUG_FULL_QUERIES_IN_RESPONSE=true):

Query Analysis: EXPLAIN vs EXPLAIN ANALYZE

The package supports two levels of query analysis for slow queries:

EXPLAIN (Execution Plan)

• What it does: Shows the query execution plan without running the query
• Enable: QUERY_DEBUG_ANALYZE=true
• Output: Tabular data showing indexes, join types, estimated rows
• Overhead: Low (~5-10ms per slow query)
• Use when: You want to understand the query plan and index usage

Example output:

EXPLAIN ANALYZE (Detailed Execution Stats)

• What it does: Actually executes the query and provides real timing/cost data
• Enable: QUERY_DEBUG_EXPLAIN_ANALYZE=true
• Output: JSON tree with actual timing, row counts, and costs for each operation
• Overhead: Higher (~20-50ms per slow query as it executes the query)
• Use when: You need detailed execution statistics and actual vs estimated comparisons

Example output:

Configuration Options:

1. Slow Queries Only (Recommended)

   • Use when: You want to analyze only problematic queries
   • Overhead: Low-Medium
   • Best for: Production/staging environments

2. Both EXPLAIN and EXPLAIN ANALYZE for Slow Queries

   • Use when: You need both execution plans and detailed stats
   • Overhead: Medium

3. All Queries (Deep Debugging)

   • Use when: You need to analyze every single query in a request
   • Overhead: High-Very High (use sparingly!)
   • Best for: Local debugging only

Important Notes:

• The _ALL variants will override slow query filtering
• Make sure to use boolean values (true/false), not strings
• After changing .env, clear config cache: php artisan config:clear

Recommendation:

• Local Development: Use EXPLAIN_ANALYZE_ALL=true for targeted debugging of specific endpoints
• Staging: Use EXPLAIN_ANALYZE=true (slow queries only) to identify bottlenecks
• Production: Disable all analysis unless debugging critical issues

View Logs

Analyze Queries

Clean Old Logs

JSON Log Format

Queries are stored as a JSON array with pretty formatting for easy reading:

Per-Route Configuration

Override settings for specific routes:

Performance

Overhead

• Minimal mode (sampling=10, backtrace=false): <1% overhead
• Standard mode (sampling=100, backtrace=true): <5% overhead
• Full analysis (explain=true): <20% overhead (dev only)

Optimization Tips

1. Use sampling in production: QUERY_DEBUG_SAMPLING=10
2. Disable backtrace: QUERY_DEBUG_BACKTRACE=false
3. Disable EXPLAIN: QUERY_DEBUG_ANALYZE=false
4. Use exclude patterns for known queries
5. Enable only in local/staging environments

Multi-Tenant Support

Optional tenant context capture for multi-tenant applications:

• Set tenant_id via config('app.tenant_id') in your application
• Or the package will try to read from config('globals.tenant')->id (if available)
• Enable in config: 'metadata' => ['tenant_id' => true]

The package works with any Laravel application - multi-tenant or single-tenant!

Advanced Features

Exclude Patterns

Skip tracking specific queries:

Metadata Collection

Configure what metadata to collect:

Troubleshooting

Queries Not Being Logged

1. Check QUERY_DEBUG_ENABLED=true in .env
2. Verify connection is in connections array
3. Check sampling rate: QUERY_DEBUG_SAMPLING=100
4. Look for exclude patterns matching your queries

High Overhead

1. Reduce sampling: QUERY_DEBUG_SAMPLING=10
2. Disable backtrace: QUERY_DEBUG_BACKTRACE=false
3. Disable EXPLAIN: QUERY_DEBUG_ANALYZE=false
4. Add exclude patterns for frequent queries

Logs Not Rotating

1. Check file permissions on storage/logs/queries/
2. Verify max_file_size_mb setting
3. Run php artisan query-debugger:clear manually

License

MIT

Support

For issues and questions, please open an issue on the GitHub repository.