PHPackages                             gladehq/laravel-query-lens - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. gladehq/laravel-query-lens

ActiveLibrary[Database & ORM](/categories/database)

gladehq/laravel-query-lens
==========================

A Laravel package for analyzing and optimizing database queries with performance insights

v1.0.0(5mo ago)2191MITPHPPHP ^8.1CI passing

Since Feb 8Pushed 5mo agoCompare

[ Source](https://github.com/gladehq/laravel-query-lens)[ Packagist](https://packagist.org/packages/gladehq/laravel-query-lens)[ RSS](/packages/gladehq-laravel-query-lens/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (3)Dependencies (8)Versions (4)Used By (0)

QueryLens
=========

[](#querylens)

**The self-hosted query performance platform for Laravel -- with AI-powered optimization, automated index recommendations, and CI pipeline regression detection.**

[![PHP Version](https://camo.githubusercontent.com/238fba3290320e81452233068c0cb0a7cce85d4244efe03b6182610765be27e3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f676c61646568712f6c61726176656c2d71756572792d6c656e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/gladehq/laravel-query-lens)[![Laravel Version](https://camo.githubusercontent.com/7c468061448b76d7ad21d0366d25630b1e0168b1f8fd2afb06911b7f0274fc93/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d31302e7825323025374325323031312e7825323025374325323031322e782d626c75653f7374796c653d666c61742d737175617265)](https://packagist.org/packages/gladehq/laravel-query-lens)[![Tests](https://camo.githubusercontent.com/d2d9e296f08f56bf408262b298e35521365b34e906a84b9d1d74ee7bd2a4ca32/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d37323025323070617373696e672d627269676874677265656e3f7374796c653d666c61742d737175617265)](https://github.com/gladehq/laravel-query-lens)[![Latest Version on Packagist](https://camo.githubusercontent.com/e73f2e19c9effe483b86ee79cb829e82195ace5d714985682da7c4acd872ebf0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f676c61646568712f6c61726176656c2d71756572792d6c656e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/gladehq/laravel-query-lens)[![License](https://camo.githubusercontent.com/659520c9d1e580ea0955171124f126487a22b747b917444dba7cab43a4c99f21/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f676c61646568712f6c61726176656c2d71756572792d6c656e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/gladehq/laravel-query-lens)

---

Why QueryLens
-------------

[](#why-querylens)

- **Self-hosted.** Your query data never leaves your servers. No external SaaS dependency, no data privacy concerns.
- **Query-focused.** Not another broad monitoring tool. QueryLens is purpose-built for database query performance -- EXPLAIN analysis, index recommendations, regression detection, and AI optimization.
- **Production-ready.** Configurable sampling rate, Octane-safe architecture, Laravel Gate authentication, and per-request isolation. Designed for high-traffic applications.
- **Actionable.** Every feature produces a concrete next step -- an index to create, a query to rewrite, a regression to investigate. Not just dashboards.
- **100% free and open-source.** Every feature is available to everyone.

---

How QueryLens Compares
----------------------

[](#how-querylens-compares)

All features included. No paid tiers. MIT licensed. Community-driven.

FeatureQueryLensDebugbarTelescopePulseNightwatchDeploymentSelf-hostedSelf-hostedSelf-hostedSelf-hostedCloudPriceFreeFreeFreeFreeSubscriptionEXPLAIN AnalysisDeep + human-readableNoNoNoNoIndex RecommendationsAutomatedNoNoNoNoRegression DetectionCI-integratedNoNoNoLimitedAI Query OptimizationOpenAI-compatibleNoNoNoNoTransaction TrackingFull lifecycleNoYesNoNoFilament PluginNative panel integrationNoNoNoNoRequest SamplingConfigurable rateNoYesYesN/AAlertingLog, Mail, SlackNoNoNoYesN+1 DetectionAutomaticYesYesNoNoCode Origin TracingFile + line numberYesYesNoNoRequest WaterfallVisual timelineYesNoNoNo---

Features
--------

[](#features)

### Dashboard Overview

[](#dashboard-overview)

Real-time query monitoring dashboard with stats overview, query list, and performance ratings. Supports live polling, search, and filtering by query type, duration, and slow status.

[![Dashboard Overview](docs/images/dashboard.png)](docs/images/dashboard.png)

### EXPLAIN Analysis with Human-Readable Output

[](#explain-analysis-with-human-readable-output)

Run EXPLAIN on any captured query directly from the dashboard. Results are parsed into human-readable descriptions explaining what the database engine is doing -- table scans, index usage, join strategies, and row estimates.

[![EXPLAIN Analysis](docs/images/explain.png)](docs/images/explain.png)

### Index Recommendation Engine

[](#index-recommendation-engine)

Analyzes query patterns over configurable time windows and recommends specific indexes to create. Outputs ready-to-run `CREATE INDEX` statements with impact estimates based on actual query frequency and duration.

### Query Regression Detection and CI Integration

[](#query-regression-detection-and-ci-integration)

Compare query performance between time periods to detect regressions. Integrates with CI/CD pipelines via the `query-lens:check-regression` command. Supports webhook notifications for automated alerting when performance degrades.

[![Regression Detection](docs/images/regression-cli.png)](docs/images/regression-cli.png)

### AI-Powered Query Optimization

[](#ai-powered-query-optimization)

Submit slow queries to any OpenAI-compatible API for optimization suggestions. Returns rewritten SQL, explanation of changes, and estimated performance improvement. Results are cached to avoid redundant API calls.

### Transaction Tracking

[](#transaction-tracking)

Track database transaction lifecycle -- begin, commit, rollback events with duration, nesting depth, and query count. Associates queries with their enclosing transaction for debugging deadlocks and long-running transactions.

### Filament Panel Integration

[](#filament-panel-integration)

Native Filament v3 plugin with real pages, Table Builder, Chart Widgets, and Stats Overview. Register with a single line in your panel configuration. Works alongside the standalone dashboard.

```
use GladeHQ\QueryLens\Filament\QueryLensPlugin;

$panel->plugin(QueryLensPlugin::make());
```

### Request Waterfall Visualization

[](#request-waterfall-visualization)

Visual timeline of all queries within a single HTTP request, showing execution order, duration bars, and overlap detection. Identifies sequential queries that could be parallelized.

[![Request Waterfall](docs/images/waterfall.png)](docs/images/waterfall.png)

### Performance Trend Tracking

[](#performance-trend-tracking)

Track P50, P95, and P99 latency over time with configurable granularity (hourly or daily). Identify slow degradation patterns before they become incidents. Top queries ranked by total impact (frequency multiplied by duration).

[![Performance Trends](docs/images/trends.png)](docs/images/trends.png)

---

Quick Start
-----------

[](#quick-start)

### 1. Install the package

[](#1-install-the-package)

```
composer require gladehq/laravel-query-lens
```

### 2. Publish configuration and migrations

[](#2-publish-configuration-and-migrations)

```
php artisan vendor:publish --tag=query-lens-config
php artisan vendor:publish --tag=query-lens-migrations
```

### 3. Run migrations

[](#3-run-migrations)

```
php artisan migrate
```

### 4. Enable in your environment

[](#4-enable-in-your-environment)

```
QUERY_LENS_ENABLED=true
```

### 5. Visit the dashboard

[](#5-visit-the-dashboard)

Open `/query-lens` in your browser.

---

Configuration
-------------

[](#configuration)

The configuration file is published to `config/query-lens.php`. Key options:

### Storage Driver

[](#storage-driver)

```
'storage' => [
    'driver' => env('QUERY_LENS_STORAGE', 'database'), // 'cache' or 'database'
    'connection' => env('QUERY_LENS_DB_CONNECTION', null),
    'table_prefix' => 'query_lens_',
    'retention_days' => env('QUERY_LENS_RETENTION_DAYS', 365),
],
```

- **cache** -- Ephemeral storage using Laravel's cache. No persistence across restarts. Good for development.
- **database** -- Persistent storage with full query history, aggregation, and trend tracking. Required for production features like regression detection and index recommendations.

### Sampling Rate

[](#sampling-rate)

```
'sampling_rate' => env('QUERY_LENS_SAMPLING_RATE', 1.0),
```

Controls what fraction of requests have their queries recorded. `1.0` records every request. `0.1` records 10%. The decision is made once per request so all queries within a sampled request are captured together.

### Authentication

[](#authentication)

```
'web_ui' => [
    'allowed_ips' => ['127.0.0.1', '::1'],
    'auth_gate' => env('QUERY_LENS_AUTH_GATE', null),
],
```

By default, the dashboard is restricted to localhost. For production, configure a Laravel Gate:

```
// In AuthServiceProvider
Gate::define('viewQueryLens', function ($user) {
    return $user->isAdmin();
});
```

```
QUERY_LENS_AUTH_GATE=viewQueryLens
```

### AI Provider Setup

[](#ai-provider-setup)

```
'ai' => [
    'enabled' => env('QUERY_LENS_AI_ENABLED', false),
    'provider' => env('QUERY_LENS_AI_PROVIDER', 'openai'),
    'api_key' => env('QUERY_LENS_AI_KEY'),
    'model' => env('QUERY_LENS_AI_MODEL', 'gpt-4o-mini'),
    'endpoint' => env('QUERY_LENS_AI_ENDPOINT', 'https://api.openai.com/v1/chat/completions'),
    'cache_ttl' => 3600,
    'rate_limit' => 10,
],
```

Works with any OpenAI-compatible API endpoint. AI features are entirely optional -- the package is fully functional without them.

### Transaction Tracking

[](#transaction-tracking-1)

```
QUERY_LENS_TRACK_TRANSACTIONS=true
```

### Alert Channels

[](#alert-channels)

```
'alerts' => [
    'enabled' => env('QUERY_LENS_ALERTS', false),
    'channels' => ['log', 'mail', 'slack'],
    'slack_webhook' => env('QUERY_LENS_SLACK_WEBHOOK'),
    'mail_to' => env('QUERY_LENS_MAIL_TO'),
    'cooldown_minutes' => 5,
],
```

---

Artisan Commands
----------------

[](#artisan-commands)

### `query-lens:aggregate`

[](#query-lensaggregate)

Pre-calculates hourly and daily performance aggregates for trend charts and top query rankings. Schedule this to run hourly in your `app/Console/Kernel.php`:

```
$schedule->command('query-lens:aggregate')->hourly();
```

### `query-lens:prune`

[](#query-lensprune)

Cleans up old query data based on the configured retention period. Schedule daily:

```
$schedule->command('query-lens:prune')->daily();
```

### `query-lens:suggest-indexes`

[](#query-lenssuggest-indexes)

Analyzes recorded query patterns and recommends database indexes:

```
php artisan query-lens:suggest-indexes --days=7
php artisan query-lens:suggest-indexes --sql="SELECT * FROM orders WHERE user_id = ? AND status = ?"
php artisan query-lens:suggest-indexes --format=json
```

### `query-lens:check-regression`

[](#query-lenscheck-regression)

Detects query performance regressions by comparing current period against the previous period. Designed for CI/CD pipelines:

```
php artisan query-lens:check-regression --period=daily --threshold=0.2
php artisan query-lens:check-regression --webhook --format=json
```

Returns exit code `1` when regressions are detected, making it suitable for CI pipeline gates.

---

Filament Integration
--------------------

[](#filament-integration)

QueryLens includes a native Filament v3 plugin. Filament is optional -- the package works without it.

### Register the plugin

[](#register-the-plugin)

```
use GladeHQ\QueryLens\Filament\QueryLensPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            QueryLensPlugin::make()
                ->dashboard()    // Query Dashboard page
                ->alerts()       // Alert Management page
                ->trends(),      // Performance Trends page
        ]);
}
```

### Customize

[](#customize)

```
QueryLensPlugin::make()
    ->dashboard(true)
    ->alerts(false)          // Disable alerts page
    ->trends(true)
    ->navigationGroup('Monitoring');
```

The plugin provides:

- **Dashboard** -- Stats overview widget, query table with search/filter/sort, View and Explain actions
- **Alerts** -- CRUD management for alert rules with modal forms
- **Trends** -- Performance and volume chart widgets, top queries table with period selector

---

Requirements
------------

[](#requirements)

- PHP 8.1+
- Laravel 10.x, 11.x, or 12.x
- Filament 3.x (optional, for panel integration)

---

Documentation
-------------

[](#documentation)

Read complete documentation at [Documentation](https://querylens.dulitharajapaksha.com/docs).

---

Contributing
------------

[](#contributing)

Contributions are welcome. Please submit pull requests against the `master` branch. Run the test suite before submitting:

```
./vendor/bin/phpunit
```

---

License
-------

[](#license)

The MIT License (MIT). See [LICENSE](LICENSE) for details.

---

Credits
-------

[](#credits)

Developed by [Dulitha Rajapaksha](https://github.com/dulithamahishka94) for [GladeHQ](https://profile.dulitharajapaksha.com).

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance70

Regular maintenance activity

Popularity10

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

3

Last Release

178d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/130d3ca03c3035d1d05d614d5555b3956c254b774bd550bbb80ed35bb99b4ad4?d=identicon)[dulithamahishka94](/maintainers/dulithamahishka94)

---

Top Contributors

[![dulithamahishka94](https://avatars.githubusercontent.com/u/64469682?v=4)](https://github.com/dulithamahishka94 "dulithamahishka94 (55 commits)")

---

Tags

composerdatabaselaravel-frameworkpackagesphp8querieslaravelprofilerdatabaseperformancesqleloquentqueryoptimizationanalyzer

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/gladehq-laravel-query-lens/health.svg)

```
[![Health](https://phpackages.com/badges/gladehq-laravel-query-lens/health.svg)](https://phpackages.com/packages/gladehq-laravel-query-lens)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.4M354](/packages/psalm-plugin-laravel)[mike-bronner/laravel-model-caching

Automatic caching for Eloquent models.

2.4k161.4k1](/packages/mike-bronner-laravel-model-caching)[forjedio/inertia-table

Backend-driven dynamic tables for Laravel + Inertia.js

272.0k](/packages/forjedio-inertia-table)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5226.7k](/packages/simplestats-io-laravel-client)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)[fleetbase/core-api

Core Framework and Resources for Fleetbase API

1239.7k25](/packages/fleetbase-core-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)