QueryLens

QueryLens reads PostgreSQL and MySQL slow query logs offline and tells you which query shapes cost the most database time, with transparent, heuristic hints about common anti-patterns.

Why it exists

A slow query log holds thousands of near-identical entries that differ only in their literal values. What you want to know is which shapes of query consume the most time and which have obvious problems. QueryLens answers that from a plain log file: no database connection, no EXPLAIN, no paid APM, and no runtime dependencies beyond the Python standard library. Its reports contain normalized queries only, so you can paste them into a pull request or a chat without leaking the data that was in your logs.

Features

• Parses PostgreSQL (log_min_duration_statement, stderr format, any log_line_prefix) and MySQL / MariaDB slow query logs, including multi-line statements, and auto-detects which one you gave it.
• Groups equivalent queries with a tokenizer-based fingerprint: literals, placeholders and comments are removed, and IN (...) (including row-value lists), multi-row VALUES and PostgreSQL ARRAY[...] literal lists collapse.
• Reports count, total, mean, p50, p95 and max time, share of total time, and (MySQL) rows examined per row sent.
• Eight heuristic hints (QL001 to QL008) that state their own limitations.
• Text, JSON (stable, versioned schema) and Markdown reports.
• CI gates: --fail-on-hint and --fail-over-ms with documented exit codes.
• Reads files, .gz files (detected by content) and stdin; streams line by line.
• Malformed entries are counted and skipped, never fatal.
• Zero runtime dependencies; Python 3.10 to 3.14.

Live demo

Try it in your browser: query-lens.netlify.app. The web playground runs this exact Python package in your browser through Pyodide, so your log is analyzed locally and never uploaded. It offers one-click sample logs, file upload or paste, search, sorting and hint filtering, per-pattern details, and the CLI's own text, Markdown and JSON reports. Demo limits: logs up to 5 MB, plain text only (no .gz or stdin), up to 500 patterns shown, and an analysis is stopped after 60 seconds. The CLI remains the primary product.

Installation

From PyPI (after the first upload — see RELEASING.md):

pipx install slowlens    # or: pip install slowlens
slowlens --version

QueryLens is the product name. On PyPI, the import package and CLI are slowlens (pip install slowlens → run slowlens). The name querylens is already taken by an unrelated project. The GitHub repository remains query-lens.

From a clone (development or before the package is on PyPI):

git clone https://github.com/yagnang-vyas/query-lens.git
cd query-lens
pipx install .          # or: python -m venv .venv && . .venv/bin/activate && pip install .
slowlens --version

Maintainer steps for GitHub Releases and PyPI Trusted Publishing are in RELEASING.md. The live demo stays on Netlify; see web/README.md.

Enabling slow query logs

PostgreSQL (postgresql.conf; reload the server afterwards). Log any statement slower than 200 ms to the standard error log:

log_min_duration_statement = 200   # milliseconds; 0 logs everything, -1 disables
logging_collector = on             # if you want the output in a file

QueryLens finds the LOG: duration: ... ms statement: ... message wherever it sits on the line, so the default log_line_prefix and custom ones both work. Use the stderr log format (not csvlog or jsonlog).

MySQL / MariaDB (my.cnf, or SET GLOBAL at runtime):

slow_query_log = 1
slow_query_log_file = /var/log/mysql/mysql-slow.log
long_query_time = 0.5              # seconds

Usage

# Top 10 shapes by total time; the format is auto-detected
slowlens examples/postgres-sample.log

# Top 5 by 95th percentile, as Markdown for a pull request comment
slowlens --top 5 --sort p95 --output markdown examples/mysql-slow-sample.log

# Machine-readable output, ignoring anything faster than 50 ms
slowlens --output json --min-duration 50 examples/postgres-sample.log

# Several files, compressed files and stdin
slowlens postgresql-2026-10-24.log postgresql-2026-10-25.log.gz
zcat mysql-slow.log.gz | slowlens --format mysql -

Using it as a CI gate

# Fail the build if any query shape has SELECT * (QL001) or a leading wildcard LIKE (QL003),
# or if any shape has a p95 above 750 ms.
slowlens --fail-on-hint QL001,QL003 --fail-over-ms 750 slow.log

The report is printed as usual, followed by a one-line reason on stderr, and the exit code is 1. Fail conditions are evaluated on all fingerprints, not only the --top subset.

Sample output

Produced by running slowlens --top 5 examples/postgres-sample.log on the synthetic sample log in this repository:

This is the beginning of the README. Read the rest at the original. Read the full README ↗