包简介

Production-safe Laravel query performance monitor with fingerprinting, aggregation, alerts, and dashboard insights.

README 文档

README

Laravel Query Watchdog is a Laravel 10-13 compatible package for monitoring slow database queries in production-like environments.

Features

Slow query capture
SQL fingerprinting
Aggregated percentile metrics
Alert engine with cooldown and notification channels
Regression detection by app version (p95 comparison)
N+1 burst heuristic detection by request fingerprint repetition
Dashboard with auth gate support
One-command package installer

Installation

composer require abirhossain/laravel-query-watchdog

php artisan query-watchdog:install --migrate

Quick Start

Enable query monitoring and alerts in .env.
Configure dashboard access with allowed emails or a custom authorizer.
Generate traffic and open /query-watchdog.

Example .env:

QUERY_WATCHDOG_ENABLED=true
QUERY_WATCHDOG_SLOW_QUERY_MS=200
QUERY_WATCHDOG_SAMPLE_RATE=0.02

QUERY_WATCHDOG_ALERTS_ENABLED=true
QUERY_WATCHDOG_ALERT_CHANNELS=log,slack
QUERY_WATCHDOG_ALERT_COOLDOWN_MINUTES=30
QUERY_WATCHDOG_REGRESSION_MULTIPLIER=2.0
QUERY_WATCHDOG_MIN_REGRESSION_MS=150
QUERY_WATCHDOG_ANALYSIS_WINDOW_MINUTES=60
QUERY_WATCHDOG_MIN_SAMPLES=20

QUERY_WATCHDOG_N_PLUS_ONE_ENABLED=true
QUERY_WATCHDOG_N_PLUS_ONE_MIN_REPETITIONS=12

QUERY_WATCHDOG_DASHBOARD_ALLOWED_EMAILS=dev1@company.com,dev2@company.com
QUERY_WATCHDOG_ALERT_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/XXX/YYY/ZZZ

Notification Channel Abstraction

Channels are configured using QUERY_WATCHDOG_ALERT_CHANNELS.

log
mail (requires QUERY_WATCHDOG_ALERT_MAIL_TO)
slack (requires QUERY_WATCHDOG_ALERT_SLACK_WEBHOOK_URL)

You can add custom channels by extending the dispatcher map in your app via container rebinding.

Dashboard Authorization Gate

By default, dashboard routes are protected by:

web
auth
can:viewQueryWatchdog

The package defines the viewQueryWatchdog gate and grants access when either:

app environment is local and QUERY_WATCHDOG_DASHBOARD_ALLOW_LOCAL=true
authenticated user email is listed in QUERY_WATCHDOG_DASHBOARD_ALLOWED_EMAILS
custom authorizer class (invokable) returns true

Production Tuning Defaults

Recommended starting values:

QUERY_WATCHDOG_SLOW_QUERY_MS=250
QUERY_WATCHDOG_SAMPLE_RATE=0.01
QUERY_WATCHDOG_ALERT_COOLDOWN_MINUTES=30
QUERY_WATCHDOG_REGRESSION_MULTIPLIER=2.0
QUERY_WATCHDOG_MIN_SAMPLES=25
QUERY_WATCHDOG_N_PLUS_ONE_MIN_REPETITIONS=15
QUERY_WATCHDOG_RAW_RETENTION_DAYS=14
QUERY_WATCHDOG_AGG_RETENTION_DAYS=90

Maintenance

Prune old records:

php artisan query-watchdog:prune

Dashboard Column Reference

Recent Fingerprints

Column	Meaning
Hash	Short prefix of the fingerprint hash that identifies a normalized query shape. Click to open detail view.
Last Seen	Relative time since this fingerprint was last captured.
Latest Duration	Duration in milliseconds of the most recent event for this fingerprint.
Route / Command	Laravel route name or console command name associated with the latest event. `n/a` means context was not available.

Top Fingerprints

Column	Meaning
Fingerprint	Fingerprint hash preview and a truncated canonical SQL shape for grouped queries.
Operation	SQL operation type detected from normalized SQL (`select`, `insert`, `update`, `delete`, or `other`).
Count	Total sampled/captured event count for this fingerprint in the selected window.
Max p95 (ms)	Highest p95 latency bucket recorded in the selected window. Useful for tail-latency monitoring.
Max duration (ms)	Single highest event duration recorded for this fingerprint in the selected window.

Fingerprint Detail: Recent Aggregates

Column	Meaning
Bucket	Minute-level aggregation timestamp for the metric row.
Count	Number of events captured in that bucket.
Slow	Number of events in that bucket with duration greater than or equal to `QUERY_WATCHDOG_SLOW_QUERY_MS`.
p50	Median latency (50th percentile) for events in the bucket.
p95	95th percentile latency for events in the bucket.
p99	99th percentile latency for events in the bucket.
Avg	Arithmetic mean latency for events in the bucket.
Max	Highest single-event latency in the bucket.

Fingerprint Detail: Recent Events

Column	Meaning
Time	Timestamp when the query event was captured.
Duration	Single event duration in milliseconds.
Connection	Database connection name used by the query.
Route / Command	Route or command context tied to this event.
SQL	Truncated raw SQL captured for that event.

abirhossain/laravel-query-watchdog 适用场景与选型建议

abirhossain/laravel-query-watchdog 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 0 次下载、GitHub Stars 达 0，最近一次更新时间为 2026 年 04 月 05 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「database」「performance」「query」「monitoring」「laravel」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 abirhossain/laravel-query-watchdog 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 abirhossain/laravel-query-watchdog 我们能提供哪些服务？

定制开发 / 二次开发

基于 abirhossain/laravel-query-watchdog 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 abirhossain/laravel-query-watchdog 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

dg/dibi 501

Dibi is Database Abstraction Library for PHP

g4/profiler 0

g4 application profiler package

sgalinski/scriptmerger 0

CSS/Javascript Minificator, Compressor and Concatenator for TYPO3 - highly configurable frontend asset optimization for CSS/JS merging, minification and compression with optional body parsing, async/defer loading, inline output, data-ignore exclusions, SRI integrity validation/calculation, external

wearerequired/jquery-light 1

WordPress mu-plugin to remove jQuery Migrate from the list of jQuery dependencies and to allow jQuery to enqueue before </body> instead of in the <head>.

novius/laravel-translation-loader 1

Store your language lines in the database, yaml or other sources

opsdev/cache-breaker 4

Create link to static resources with cache-breaking segment based on md5 of the file

abirhossain/laravel-query-watchdog

包简介

关键字：