flask-lens 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. flask_lens-0.2.0/.gitignore +27 -0
  2. flask_lens-0.2.0/CHANGELOG.md +42 -0
  3. flask_lens-0.2.0/LICENSE +21 -0
  4. flask_lens-0.2.0/PKG-INFO +304 -0
  5. flask_lens-0.2.0/README.md +251 -0
  6. flask_lens-0.2.0/benchmarks/bench_overhead.py +169 -0
  7. flask_lens-0.2.0/docs/assets/compare-diff.png +0 -0
  8. flask_lens-0.2.0/docs/assets/exception-inspector.png +0 -0
  9. flask_lens-0.2.0/docs/assets/flamegraph.png +0 -0
  10. flask_lens-0.2.0/docs/assets/overview-n1.png +0 -0
  11. flask_lens-0.2.0/docs/assets/sql-explain.png +0 -0
  12. flask_lens-0.2.0/docs/configuration.md +62 -0
  13. flask_lens-0.2.0/docs/testing-guardrails.md +87 -0
  14. flask_lens-0.2.0/examples/bookstore_app.py +270 -0
  15. flask_lens-0.2.0/examples/minimal_app.py +21 -0
  16. flask_lens-0.2.0/pyproject.toml +145 -0
  17. flask_lens-0.2.0/src/flask_lens/__init__.py +56 -0
  18. flask_lens-0.2.0/src/flask_lens/blueprint.py +261 -0
  19. flask_lens-0.2.0/src/flask_lens/cli.py +130 -0
  20. flask_lens-0.2.0/src/flask_lens/collectors/__init__.py +43 -0
  21. flask_lens-0.2.0/src/flask_lens/collectors/context.py +126 -0
  22. flask_lens-0.2.0/src/flask_lens/collectors/exceptions.py +79 -0
  23. flask_lens-0.2.0/src/flask_lens/collectors/http_outgoing.py +267 -0
  24. flask_lens-0.2.0/src/flask_lens/collectors/logging_handler.py +68 -0
  25. flask_lens-0.2.0/src/flask_lens/collectors/profiler.py +280 -0
  26. flask_lens-0.2.0/src/flask_lens/config.py +210 -0
  27. flask_lens-0.2.0/src/flask_lens/extension.py +713 -0
  28. flask_lens-0.2.0/src/flask_lens/models.py +487 -0
  29. flask_lens-0.2.0/src/flask_lens/py.typed +0 -0
  30. flask_lens-0.2.0/src/flask_lens/pytest_plugin.py +177 -0
  31. flask_lens-0.2.0/src/flask_lens/redaction.py +276 -0
  32. flask_lens-0.2.0/src/flask_lens/sql/__init__.py +38 -0
  33. flask_lens-0.2.0/src/flask_lens/sql/analyzer.py +133 -0
  34. flask_lens-0.2.0/src/flask_lens/sql/explain.py +196 -0
  35. flask_lens-0.2.0/src/flask_lens/sql/listener.py +454 -0
  36. flask_lens-0.2.0/src/flask_lens/sql/normalizer.py +184 -0
  37. flask_lens-0.2.0/src/flask_lens/storage/__init__.py +21 -0
  38. flask_lens-0.2.0/src/flask_lens/storage/base.py +154 -0
  39. flask_lens-0.2.0/src/flask_lens/storage/memory.py +261 -0
  40. flask_lens-0.2.0/src/flask_lens/storage/sqlite.py +528 -0
  41. flask_lens-0.2.0/src/flask_lens/testing.py +189 -0
  42. flask_lens-0.2.0/src/flask_lens/ui/__init__.py +1 -0
  43. flask_lens-0.2.0/src/flask_lens/ui/app.js +1829 -0
  44. flask_lens-0.2.0/src/flask_lens/ui/index.html +269 -0
  45. flask_lens-0.2.0/src/flask_lens/ui/styles.css +1525 -0
  46. flask_lens-0.2.0/tests/__init__.py +0 -0
  47. flask_lens-0.2.0/tests/conftest.py +146 -0
  48. flask_lens-0.2.0/tests/test_blueprint_replay_and_sse.py +149 -0
  49. flask_lens-0.2.0/tests/test_bug_hunt_regressions.py +411 -0
  50. flask_lens-0.2.0/tests/test_cli.py +50 -0
  51. flask_lens-0.2.0/tests/test_edge_cases.py +314 -0
  52. flask_lens-0.2.0/tests/test_extension_and_sqlalchemy.py +221 -0
  53. flask_lens-0.2.0/tests/test_outgoing_http.py +114 -0
  54. flask_lens-0.2.0/tests/test_redaction.py +92 -0
  55. flask_lens-0.2.0/tests/test_sql_normalizer_and_analyzer.py +145 -0
  56. flask_lens-0.2.0/tests/test_storage.py +198 -0
  57. flask_lens-0.2.0/tests/test_testing_and_pytest_plugin.py +127 -0
@@ -0,0 +1,27 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.egg-info/
6
+ .eggs/
7
+ build/
8
+ dist/
9
+ .venv/
10
+ venv/
11
+
12
+ # Tooling
13
+ .pytest_cache/
14
+ .mypy_cache/
15
+ .ruff_cache/
16
+ .coverage
17
+ htmlcov/
18
+ coverage.xml
19
+
20
+ # Runtime telemetry databases
21
+ .flask_lens.sqlite3*
22
+ *.sqlite3*
23
+
24
+ # OS / Editor
25
+ .DS_Store
26
+ .vscode/
27
+ .idea/
@@ -0,0 +1,42 @@
1
+ # Changelog
2
+
3
+ All notable changes to `flask-lens` are documented in this file.
4
+
5
+ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ ## [0.2.0] - 2026-11-22
8
+
9
+ ### Added
10
+ - `@pytest.mark.num_queries(N)` declarative exact query-count pytest marker alongside `max_queries` and `no_n_plus_one`.
11
+ - Automatic redaction of sensitive query-string parameters and URL credentials (`redact_query_string`, `redact_url`) across incoming requests and outgoing HTTP traces.
12
+ - Deep-link SPA URL routing (`/__lens/requests/<id>`, `/__lens/endpoints`, `/__lens/sql`, `/__lens/exceptions`, `/__lens/compare`), keyboard navigation (`↑`/`↓`/`Enter`) inside `⌘K`, per-query **Copy SQL**, and live relative timestamp refresh.
13
+
14
+ ### Fixed
15
+ - **Multi-app & multi-engine isolation:** Assign unique internal engine IDs so multiple Flask apps or SQLAlchemy engines sharing `"default"` bind names never cross-contaminate captured queries or `capture_queries(...)` assertions.
16
+ - **`async def` Flask 3.x views with `@lens.profile`:** Mark view functions directly without wrapping them in a sync function, preserving `inspect.iscoroutinefunction` and removing wrapper frame noise from Flamegraphs.
17
+ - **Security hardening:**
18
+ - Block replay path-traversal, URL-encoded, and query-string bypass attempts targeting `url_prefix` (e.g., `/foo/../__lens/api/clear`, `/__lens?a=1`, `/%5f%5flens`).
19
+ - Harden `is_safe_explainable_sql()` against apostrophes inside `--` comments, unclosed `/*` block comments, and data-modifying CTEs (`WITH d AS (DELETE ...)`).
20
+ - Restrict `/__lens/assets/<filename>` to an explicit static asset allowlist (`styles.css`, `app.js`).
21
+ - **Config immutability & validation:** Validate `LensConfig` in `__post_init__` and use `copy_with()` inside `init_app()` so shared configs are never mutated across apps.
22
+ - **SQLite storage:** Escape SQL `LIKE` wildcards (`%`, `_`, `\`) during search and select the chronologically latest `sample_request_id` and `sample_call_site` in `sql_stats()`.
23
+ - **Multi-app logging deduplication:** Use a single ref-counted `LensLogHandler` so log records are never duplicated when multiple `Lens` instances coexist in one process.
24
+ - **SSE clean shutdown:** Signal active `/__lens/api/stream` subscribers immediately on `lens.close()`.
25
+ - **Path prefix classification:** Replace string `startswith` with `os.path.commonpath` when checking `app_root` and stdlib boundaries.
26
+ - **Schema-qualified SQL tables:** Extract `"schema"."table"` accurately in `extract_tables()`, and normalize `IN (..., NULL)` and PostgreSQL `E'...'` strings.
27
+
28
+ ## [0.1.0] - 2026-11-21
29
+
30
+ ### Added
31
+ - Core `Lens` Flask extension supporting direct initialization and the `init_app()` factory pattern.
32
+ - Zero-dependency embedded DevTools SPA mounted at `/__lens` with dark/light themes, real-time SSE streaming, `⌘K` command palette, and keyboard navigation.
33
+ - SQLAlchemy 2.0 & Flask-SQLAlchemy 3.x query instrumentation with SQL canonicalization, N+1 detection, exact duplicate detection, slow-query tagging, user-code source snippets, and safe read-only `EXPLAIN` / `EXPLAIN QUERY PLAN` diagnostics.
34
+ - Per-request `cProfile` profiler generating interactive zoomable SVG flamegraphs and flat hotspot tables (`profile_mode`: `always`, `slow`, `on_demand`, `off`, plus `@lens.profile` decorator and `X-Lens-Profile: 1` header).
35
+ - Outgoing HTTP instrumentation for `urllib3` (`requests`) and `httpx` (sync & async).
36
+ - Request-scoped structured logging, template rendering spans, custom `lens.span()` / `lens.event()` hooks, and interactive exception tracebacks with redacted local variables.
37
+ - Request Replay modal, cURL export, and Before/After Request Diff comparator.
38
+ - Endpoint latency analytics (p50/p95/p99), SQL Fingerprint Explorer, and grouped Exceptions view.
39
+ - W3C `Server-Timing` HTTP response header integration.
40
+ - Embedded SQLite WAL ring-buffer storage backend and thread-safe in-memory storage backend.
41
+ - Django `assertNumQueries` counterparts (`capture_queries`, `assert_num_queries`, `assert_max_queries`, `assert_no_n_plus_one`) and auto-registered `pytest11` plugin (`@pytest.mark.max_queries`, `@pytest.mark.no_n_plus_one`).
42
+ - Flask CLI commands under `flask lens` (`status`, `stats`, `slow`, `clear`, `export`).
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Duhan Güler
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,304 @@
1
+ Metadata-Version: 2.5
2
+ Name: flask-lens
3
+ Version: 0.2.0
4
+ Summary: Real-time developer observability, SQL/N+1 profiler, EXPLAIN analyzer, cProfile flamegraph, request replayer, and pytest query-budget guardrails for Flask.
5
+ Project-URL: Homepage, https://github.com/duhanguler/flask-lens
6
+ Project-URL: Repository, https://github.com/duhanguler/flask-lens
7
+ Project-URL: Documentation, https://github.com/duhanguler/flask-lens#readme
8
+ Project-URL: Issues, https://github.com/duhanguler/flask-lens/issues
9
+ Project-URL: Changelog, https://github.com/duhanguler/flask-lens/blob/main/CHANGELOG.md
10
+ Author-email: Duhan Güler <45712664+duhanguler@users.noreply.github.com>
11
+ License: MIT
12
+ License-File: LICENSE
13
+ Keywords: assert-num-queries,debug,debugging,django-silk,flamegraph,flask,n-plus-one,observability,profiler,pytest,sqlalchemy,telescope
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Environment :: Web Environment
16
+ Classifier: Framework :: Flask
17
+ Classifier: Framework :: Pytest
18
+ Classifier: Intended Audience :: Developers
19
+ Classifier: License :: OSI Approved :: MIT License
20
+ Classifier: Operating System :: OS Independent
21
+ Classifier: Programming Language :: Python :: 3
22
+ Classifier: Programming Language :: Python :: 3.10
23
+ Classifier: Programming Language :: Python :: 3.11
24
+ Classifier: Programming Language :: Python :: 3.12
25
+ Classifier: Programming Language :: Python :: 3.13
26
+ Classifier: Topic :: Internet :: WWW/HTTP :: WSGI
27
+ Classifier: Topic :: Software Development :: Debuggers
28
+ Classifier: Topic :: Software Development :: Testing
29
+ Classifier: Typing :: Typed
30
+ Requires-Python: >=3.10
31
+ Requires-Dist: flask>=2.3.0
32
+ Requires-Dist: werkzeug>=2.3.0
33
+ Provides-Extra: dev
34
+ Requires-Dist: asgiref>=3.8.0; extra == 'dev'
35
+ Requires-Dist: flask-sqlalchemy>=3.1.0; extra == 'dev'
36
+ Requires-Dist: httpx>=0.25.0; extra == 'dev'
37
+ Requires-Dist: mypy>=1.11.0; extra == 'dev'
38
+ Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
39
+ Requires-Dist: pytest>=8.0.0; extra == 'dev'
40
+ Requires-Dist: requests>=2.28.0; extra == 'dev'
41
+ Requires-Dist: ruff>=0.6.0; extra == 'dev'
42
+ Requires-Dist: sqlalchemy>=2.0.0; extra == 'dev'
43
+ Requires-Dist: types-requests>=2.31.0; extra == 'dev'
44
+ Provides-Extra: flask-sqlalchemy
45
+ Requires-Dist: flask-sqlalchemy>=3.1.0; extra == 'flask-sqlalchemy'
46
+ Requires-Dist: sqlalchemy>=2.0.0; extra == 'flask-sqlalchemy'
47
+ Provides-Extra: http
48
+ Requires-Dist: httpx>=0.25.0; extra == 'http'
49
+ Requires-Dist: requests>=2.28.0; extra == 'http'
50
+ Provides-Extra: sqlalchemy
51
+ Requires-Dist: sqlalchemy>=2.0.0; extra == 'sqlalchemy'
52
+ Description-Content-Type: text/markdown
53
+
54
+ # flask-lens
55
+
56
+ [![CI](https://github.com/duhanguler/flask-lens/actions/workflows/ci.yml/badge.svg)](https://github.com/duhanguler/flask-lens/actions/workflows/ci.yml)
57
+ [![PyPI](https://img.shields.io/pypi/v/flask-lens?style=flat-square&color=0D7A52&logo=pypi&logoColor=white)](https://pypi.org/project/flask-lens/)
58
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776ab.svg)](https://www.python.org/downloads/)
59
+ [![Typed](https://img.shields.io/badge/typing-PEP%20561%20strict-0ea5e9.svg)](https://github.com/duhanguler/flask-lens/blob/main/src/flask_lens/py.typed)
60
+ [![License: MIT](https://img.shields.io/badge/license-MIT-10b981.svg)](https://github.com/duhanguler/flask-lens/blob/main/LICENSE)
61
+
62
+ **Real-time developer observability, SQL/N+1 profiler, EXPLAIN analyzer, cProfile flamegraph, request replayer, and Django-style `assertNumQueries` guardrails for Flask — in two lines of code.**
63
+
64
+ Mount `Lens(app, db=db)` to open a zero-dependency DevTools console at `/__lens` that works across **JSON REST APIs, HTMX, webhooks, SPAs, and server-rendered HTML**.
65
+
66
+ ![flask-lens Overview and N+1 Detection](https://raw.githubusercontent.com/duhanguler/flask-lens/main/docs/assets/overview-n1.png)
67
+
68
+ ---
69
+
70
+ ## Why `flask-lens`?
71
+
72
+ Django ships `assertNumQueries` in core and has `django-silk` for persistent SQL and Python profiling; Laravel has Telescope. In Flask, `Flask-DebugToolbar` only injects a sidebar into `text/html` responses — leaving REST APIs, SPAs, redirects, and background webhooks blind and losing history on every request.
73
+
74
+ | Capability | `flask-lens` | `Flask-DebugToolbar` | `django-silk` / Django |
75
+ | :--- | :---: | :---: | :---: |
76
+ | Works on JSON APIs, HTMX & Webhooks | Yes | No (HTML only) | Yes |
77
+ | Persistent request history & live SSE stream | Yes (SQLite WAL / Memory) | No | Yes (DB tables) |
78
+ | Automatic SQL N+1 & duplicate detection with `file:line` | Yes | Duplicate count only | Manual inspection |
79
+ | Safe read-only `EXPLAIN` + full-table-scan warnings | Yes | SQLite/PG basic | Yes |
80
+ | Per-request `cProfile` interactive SVG flamegraph | Yes | Flat table only | cProfile graph |
81
+ | Outgoing HTTP (`requests`/`urllib3`/`httpx`), logs & custom spans | Yes | Logs only | Partial |
82
+ | Interactive Request Replay + Before/After Diff comparator | Yes | No | No |
83
+ | `assert_num_queries` / `@pytest.mark.no_n_plus_one` CI guardrails | Yes (built-in pytest plugin) | No | `assertNumQueries` |
84
+ | External infrastructure required | **None** | None | Database migrations |
85
+
86
+ ---
87
+
88
+ ## Installation
89
+
90
+ ```bash
91
+ pip install flask-lens
92
+ ```
93
+
94
+ `flask-lens` depends **only on `flask` and `werkzeug`**. SQLAlchemy, Flask-SQLAlchemy, `requests`, and `httpx` integrations activate automatically when installed:
95
+
96
+ ```bash
97
+ pip install "flask-lens[flask-sqlalchemy]"
98
+ ```
99
+
100
+ ---
101
+
102
+ ## Two-Line Quickstart
103
+
104
+ ### Direct initialization
105
+
106
+ ```python
107
+ from flask import Flask
108
+ from flask_sqlalchemy import SQLAlchemy
109
+ from flask_lens import Lens
110
+
111
+ app = Flask(__name__)
112
+ app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
113
+
114
+ db = SQLAlchemy(app)
115
+ lens = Lens(app, db=db) # Console available at http://127.0.0.1:5000/__lens
116
+ ```
117
+
118
+ ### Application factory pattern
119
+
120
+ ```python
121
+ from flask import Flask
122
+ from flask_sqlalchemy import SQLAlchemy
123
+ from flask_lens import Lens
124
+
125
+ db = SQLAlchemy()
126
+ lens = Lens()
127
+
128
+
129
+ def create_app() -> Flask:
130
+ app = Flask(__name__)
131
+ app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
132
+ db.init_app(app)
133
+ lens.init_app(app, db=db)
134
+ return app
135
+ ```
136
+
137
+ ### Run the interactive bookstore demo
138
+
139
+ Clone the repo and fire pre-built N+1, eager-load, full-table-scan, CPU flamegraph, secret redaction, and exception scenarios in seconds:
140
+
141
+ ```bash
142
+ git clone https://github.com/duhanguler/flask-lens.git
143
+ cd flask-lens
144
+ uv venv && uv pip install -e ".[dev]"
145
+ python examples/bookstore_app.py
146
+ # Open http://127.0.0.1:5050/ and http://127.0.0.1:5050/__lens
147
+ ```
148
+
149
+ ---
150
+
151
+ ## Feature Tour
152
+
153
+ ### 1. SQL Inspector, Source Context & One-Click `EXPLAIN`
154
+
155
+ Every SQLAlchemy query is canonicalized into a normalized fingerprint, tagged for **N+1**, **duplicate**, and **slow** behavior, and mapped back to your exact application source line. Clicking **EXPLAIN** runs a read-only `EXPLAIN` / `EXPLAIN QUERY PLAN` (strictly rejecting mutating or multi-statement SQL) and highlights full table scans (`SCAN` / `Seq Scan`) and temporary sorts (`USE TEMP B-TREE` / `filesort`).
156
+
157
+ ![SQL Inspector, Source Snippet and SQLite EXPLAIN](https://raw.githubusercontent.com/duhanguler/flask-lens/main/docs/assets/sql-explain.png)
158
+
159
+ ### 2. Interactive `cProfile` SVG Flamegraph
160
+
161
+ Inspect per-request CPU hotspots with a zoomable SVG flamegraph and flat function table color-coded by layer (**User Code**, **Framework**, **Third-Party**, **Stdlib**). Control profiling scope via `profile_mode` (`"always"`, `"slow"`, `"on_demand"`, `"off"`), the `@lens.profile` view decorator, or the `X-Lens-Profile: 1` request header.
162
+
163
+ ![Interactive cProfile SVG Flamegraph](https://raw.githubusercontent.com/duhanguler/flask-lens/main/docs/assets/flamegraph.png)
164
+
165
+ ### 3. Request Replay & Before/After Diff Comparator
166
+
167
+ Edit headers, query parameters, or JSON payloads directly inside `/__lens`, replay the request against your live Flask app, and compare **Before vs After** latency, SQL query count, N+1 resolution status, and normalized SQL fingerprint diffs side by side.
168
+
169
+ ![Before and After Request Comparison Diff](https://raw.githubusercontent.com/duhanguler/flask-lens/main/docs/assets/compare-diff.png)
170
+
171
+ ### 4. Structured Exception Inspector with Secret Redaction
172
+
173
+ Unhandled exceptions are captured in both `debug`/`testing` and production modes with clickable stack frames, source context lines, and a local-variable table where sensitive keys (`password`, `token`, `api_key`, `secret`, `Authorization`, `Cookie`, etc.) are automatically scrubbed to `[REDACTED]`.
174
+
175
+ ![Exception Traceback and Redacted Local Variables](https://raw.githubusercontent.com/duhanguler/flask-lens/main/docs/assets/exception-inspector.png)
176
+
177
+ ---
178
+
179
+ ## Django `assertNumQueries` & Pytest Guardrails
180
+
181
+ Lock in SQL query budgets and catch N+1 regressions directly in CI — without writing boilerplate SQLAlchemy event listeners:
182
+
183
+ ```python
184
+ import pytest
185
+ from flask_lens import assert_max_queries, assert_no_n_plus_one, assert_num_queries
186
+
187
+
188
+ def test_authors_endpoint(client, db):
189
+ with assert_num_queries(db, 2):
190
+ resp = client.get("/api/authors?optimized=1")
191
+ assert resp.status_code == 200
192
+
193
+ with assert_no_n_plus_one(db, threshold=3):
194
+ client.get("/api/authors?optimized=1")
195
+
196
+
197
+ # Or declaratively via the auto-registered pytest11 plugin:
198
+ @pytest.mark.max_queries(2)
199
+ @pytest.mark.no_n_plus_one
200
+ def test_authors_declarative(client, db):
201
+ assert client.get("/api/authors?optimized=1").status_code == 200
202
+ ```
203
+
204
+ See [docs/testing-guardrails.md](https://github.com/duhanguler/flask-lens/blob/main/docs/testing-guardrails.md) for fixtures, custom thresholds, and failure reports.
205
+
206
+ ---
207
+
208
+ ## Custom Spans, Events & `Server-Timing`
209
+
210
+ Annotate business logic on the request waterfall with zero ceremony:
211
+
212
+ ```python
213
+ @app.post("/api/orders")
214
+ @lens.profile # Profile even when profile_mode="on_demand"
215
+ def create_order():
216
+ with lens.span("payment.authorize", provider="stripe") as meta:
217
+ charge = authorize_payment()
218
+ meta["charge_id"] = charge.id
219
+
220
+ lens.event("order.created", {"amount_cents": 4900})
221
+ return jsonify({"ok": True}), 201
222
+ ```
223
+
224
+ Every captured response also emits a standard W3C `Server-Timing` header so timings appear natively in Chrome DevTools:
225
+
226
+ ```http
227
+ Server-Timing: total;dur=10.90, sql;dur=0.12;desc="13 queries"
228
+ X-Lens-Request-Id: 24e3ed17d96c4a58
229
+ ```
230
+
231
+ ---
232
+
233
+ ## Flask CLI Integration
234
+
235
+ `flask-lens` registers a `flask lens` command group automatically:
236
+
237
+ ```bash
238
+ flask lens status # Active config, watched engines, stored counts
239
+ flask lens stats --limit 15 # Per-endpoint p50/p95/p99 latency, SQL & N+1 table
240
+ flask lens slow --limit 10 # Top normalized SQL fingerprints by total time
241
+ flask lens export report.json # Export full telemetry snapshot for bug reports
242
+ flask lens clear # Wipe stored ring-buffer telemetry
243
+ ```
244
+
245
+ ---
246
+
247
+ ## Measured Overhead Benchmarks
248
+
249
+ Measured locally with [`benchmarks/bench_overhead.py`](https://github.com/duhanguler/flask-lens/blob/main/benchmarks/bench_overhead.py) (CPython 3.13, macOS Apple Silicon, 300 iterations after 30 warmup iterations per scenario):
250
+
251
+ | Scenario | JSON Route (`/ping`) Mean | JSON Delta | SQLAlchemy Route (`/items`) Mean | SQLAlchemy Delta |
252
+ | :--- | ---: | ---: | ---: | ---: |
253
+ | Plain Flask (baseline) | `0.090 ms` | baseline | `0.202 ms` | baseline |
254
+ | `Lens(enabled=False)` | `0.084 ms` | `~0.000 ms` | `0.200 ms` | `~0.000 ms` |
255
+ | `Lens(storage="memory", profile_mode="off")` | `0.147 ms` | `+0.057 ms` | `0.375 ms` | `+0.172 ms` |
256
+ | `Lens(storage="sqlite", profile_mode="off")` | `0.249 ms` | `+0.159 ms` | `0.604 ms` | `+0.401 ms` |
257
+ | `Lens(storage="sqlite", profile_mode="always")` | `1.302 ms` | `+1.212 ms` | `6.339 ms` | `+6.137 ms` |
258
+
259
+ Reproduce on your hardware with `make bench`. For high-traffic staging runs, set `profile_mode="on_demand"` or `profile_mode="slow"` to keep request capture under **0.4 ms**.
260
+
261
+ ---
262
+
263
+ ## Architecture
264
+
265
+ ```mermaid
266
+ flowchart LR
267
+ Req["Flask HTTP Request"] --> Hooks["Lens Lifecycle Hooks<br/>(before / after / teardown / signals)"]
268
+ Hooks --> Ctx["ContextVar RequestContext"]
269
+ SQLA["SQLAlchemy Engine Events"] --> Ctx
270
+ HTTP["urllib3 / httpx Wrappers"] --> Ctx
271
+ Logs["Request-Scoped LogHandler"] --> Ctx
272
+ Prof["cProfile Collector"] --> Ctx
273
+ Ctx --> Analyzer["SQL Normalizer & N+1 Analyzer<br/>+ Secret Redactor"]
274
+ Analyzer --> Store["SQLite WAL / Memory Ring-Buffer"]
275
+ Analyzer --> SSE["SSE Broadcaster"]
276
+ Store --> BP["/__lens Blueprint<br/>(REST API + Embedded SPA)"]
277
+ SSE --> BP
278
+ ```
279
+
280
+ ---
281
+
282
+ ## Security & Production Guidance
283
+
284
+ - **Access Control:** Gate `/__lens` outside localhost using `authorize=lambda req: ...`.
285
+ - **Automatic Redaction:** Sensitive headers (`Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key`), JSON/form fields, SQL bind parameters, and exception locals are redacted to `[REDACTED]` by default before persistence.
286
+ - **Safe `EXPLAIN`:** Strictly limited to single, read-only `SELECT` statements; mutating DML/DDL and multi-statement queries are rejected.
287
+ - **Safe Replay:** Restricted to relative application paths; `/__lens` routes and external URLs are rejected to prevent recursion and SSRF.
288
+
289
+ Read [docs/configuration.md](https://github.com/duhanguler/flask-lens/blob/main/docs/configuration.md) and [SECURITY.md](https://github.com/duhanguler/flask-lens/blob/main/SECURITY.md) for full details.
290
+
291
+ ---
292
+
293
+ ## Development
294
+
295
+ ```bash
296
+ make install # Create .venv via uv and install dev dependencies
297
+ make check # ruff lint + format check + mypy --strict + pytest coverage
298
+ make bench # Run reproducible WSGI overhead benchmarks
299
+ make build # Build wheel & sdist via hatchling
300
+ ```
301
+
302
+ ## License
303
+
304
+ MIT — see [LICENSE](https://github.com/duhanguler/flask-lens/blob/main/LICENSE).
@@ -0,0 +1,251 @@
1
+ # flask-lens
2
+
3
+ [![CI](https://github.com/duhanguler/flask-lens/actions/workflows/ci.yml/badge.svg)](https://github.com/duhanguler/flask-lens/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/flask-lens?style=flat-square&color=0D7A52&logo=pypi&logoColor=white)](https://pypi.org/project/flask-lens/)
5
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776ab.svg)](https://www.python.org/downloads/)
6
+ [![Typed](https://img.shields.io/badge/typing-PEP%20561%20strict-0ea5e9.svg)](https://github.com/duhanguler/flask-lens/blob/main/src/flask_lens/py.typed)
7
+ [![License: MIT](https://img.shields.io/badge/license-MIT-10b981.svg)](https://github.com/duhanguler/flask-lens/blob/main/LICENSE)
8
+
9
+ **Real-time developer observability, SQL/N+1 profiler, EXPLAIN analyzer, cProfile flamegraph, request replayer, and Django-style `assertNumQueries` guardrails for Flask — in two lines of code.**
10
+
11
+ Mount `Lens(app, db=db)` to open a zero-dependency DevTools console at `/__lens` that works across **JSON REST APIs, HTMX, webhooks, SPAs, and server-rendered HTML**.
12
+
13
+ ![flask-lens Overview and N+1 Detection](https://raw.githubusercontent.com/duhanguler/flask-lens/main/docs/assets/overview-n1.png)
14
+
15
+ ---
16
+
17
+ ## Why `flask-lens`?
18
+
19
+ Django ships `assertNumQueries` in core and has `django-silk` for persistent SQL and Python profiling; Laravel has Telescope. In Flask, `Flask-DebugToolbar` only injects a sidebar into `text/html` responses — leaving REST APIs, SPAs, redirects, and background webhooks blind and losing history on every request.
20
+
21
+ | Capability | `flask-lens` | `Flask-DebugToolbar` | `django-silk` / Django |
22
+ | :--- | :---: | :---: | :---: |
23
+ | Works on JSON APIs, HTMX & Webhooks | Yes | No (HTML only) | Yes |
24
+ | Persistent request history & live SSE stream | Yes (SQLite WAL / Memory) | No | Yes (DB tables) |
25
+ | Automatic SQL N+1 & duplicate detection with `file:line` | Yes | Duplicate count only | Manual inspection |
26
+ | Safe read-only `EXPLAIN` + full-table-scan warnings | Yes | SQLite/PG basic | Yes |
27
+ | Per-request `cProfile` interactive SVG flamegraph | Yes | Flat table only | cProfile graph |
28
+ | Outgoing HTTP (`requests`/`urllib3`/`httpx`), logs & custom spans | Yes | Logs only | Partial |
29
+ | Interactive Request Replay + Before/After Diff comparator | Yes | No | No |
30
+ | `assert_num_queries` / `@pytest.mark.no_n_plus_one` CI guardrails | Yes (built-in pytest plugin) | No | `assertNumQueries` |
31
+ | External infrastructure required | **None** | None | Database migrations |
32
+
33
+ ---
34
+
35
+ ## Installation
36
+
37
+ ```bash
38
+ pip install flask-lens
39
+ ```
40
+
41
+ `flask-lens` depends **only on `flask` and `werkzeug`**. SQLAlchemy, Flask-SQLAlchemy, `requests`, and `httpx` integrations activate automatically when installed:
42
+
43
+ ```bash
44
+ pip install "flask-lens[flask-sqlalchemy]"
45
+ ```
46
+
47
+ ---
48
+
49
+ ## Two-Line Quickstart
50
+
51
+ ### Direct initialization
52
+
53
+ ```python
54
+ from flask import Flask
55
+ from flask_sqlalchemy import SQLAlchemy
56
+ from flask_lens import Lens
57
+
58
+ app = Flask(__name__)
59
+ app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
60
+
61
+ db = SQLAlchemy(app)
62
+ lens = Lens(app, db=db) # Console available at http://127.0.0.1:5000/__lens
63
+ ```
64
+
65
+ ### Application factory pattern
66
+
67
+ ```python
68
+ from flask import Flask
69
+ from flask_sqlalchemy import SQLAlchemy
70
+ from flask_lens import Lens
71
+
72
+ db = SQLAlchemy()
73
+ lens = Lens()
74
+
75
+
76
+ def create_app() -> Flask:
77
+ app = Flask(__name__)
78
+ app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
79
+ db.init_app(app)
80
+ lens.init_app(app, db=db)
81
+ return app
82
+ ```
83
+
84
+ ### Run the interactive bookstore demo
85
+
86
+ Clone the repo and fire pre-built N+1, eager-load, full-table-scan, CPU flamegraph, secret redaction, and exception scenarios in seconds:
87
+
88
+ ```bash
89
+ git clone https://github.com/duhanguler/flask-lens.git
90
+ cd flask-lens
91
+ uv venv && uv pip install -e ".[dev]"
92
+ python examples/bookstore_app.py
93
+ # Open http://127.0.0.1:5050/ and http://127.0.0.1:5050/__lens
94
+ ```
95
+
96
+ ---
97
+
98
+ ## Feature Tour
99
+
100
+ ### 1. SQL Inspector, Source Context & One-Click `EXPLAIN`
101
+
102
+ Every SQLAlchemy query is canonicalized into a normalized fingerprint, tagged for **N+1**, **duplicate**, and **slow** behavior, and mapped back to your exact application source line. Clicking **EXPLAIN** runs a read-only `EXPLAIN` / `EXPLAIN QUERY PLAN` (strictly rejecting mutating or multi-statement SQL) and highlights full table scans (`SCAN` / `Seq Scan`) and temporary sorts (`USE TEMP B-TREE` / `filesort`).
103
+
104
+ ![SQL Inspector, Source Snippet and SQLite EXPLAIN](https://raw.githubusercontent.com/duhanguler/flask-lens/main/docs/assets/sql-explain.png)
105
+
106
+ ### 2. Interactive `cProfile` SVG Flamegraph
107
+
108
+ Inspect per-request CPU hotspots with a zoomable SVG flamegraph and flat function table color-coded by layer (**User Code**, **Framework**, **Third-Party**, **Stdlib**). Control profiling scope via `profile_mode` (`"always"`, `"slow"`, `"on_demand"`, `"off"`), the `@lens.profile` view decorator, or the `X-Lens-Profile: 1` request header.
109
+
110
+ ![Interactive cProfile SVG Flamegraph](https://raw.githubusercontent.com/duhanguler/flask-lens/main/docs/assets/flamegraph.png)
111
+
112
+ ### 3. Request Replay & Before/After Diff Comparator
113
+
114
+ Edit headers, query parameters, or JSON payloads directly inside `/__lens`, replay the request against your live Flask app, and compare **Before vs After** latency, SQL query count, N+1 resolution status, and normalized SQL fingerprint diffs side by side.
115
+
116
+ ![Before and After Request Comparison Diff](https://raw.githubusercontent.com/duhanguler/flask-lens/main/docs/assets/compare-diff.png)
117
+
118
+ ### 4. Structured Exception Inspector with Secret Redaction
119
+
120
+ Unhandled exceptions are captured in both `debug`/`testing` and production modes with clickable stack frames, source context lines, and a local-variable table where sensitive keys (`password`, `token`, `api_key`, `secret`, `Authorization`, `Cookie`, etc.) are automatically scrubbed to `[REDACTED]`.
121
+
122
+ ![Exception Traceback and Redacted Local Variables](https://raw.githubusercontent.com/duhanguler/flask-lens/main/docs/assets/exception-inspector.png)
123
+
124
+ ---
125
+
126
+ ## Django `assertNumQueries` & Pytest Guardrails
127
+
128
+ Lock in SQL query budgets and catch N+1 regressions directly in CI — without writing boilerplate SQLAlchemy event listeners:
129
+
130
+ ```python
131
+ import pytest
132
+ from flask_lens import assert_max_queries, assert_no_n_plus_one, assert_num_queries
133
+
134
+
135
+ def test_authors_endpoint(client, db):
136
+ with assert_num_queries(db, 2):
137
+ resp = client.get("/api/authors?optimized=1")
138
+ assert resp.status_code == 200
139
+
140
+ with assert_no_n_plus_one(db, threshold=3):
141
+ client.get("/api/authors?optimized=1")
142
+
143
+
144
+ # Or declaratively via the auto-registered pytest11 plugin:
145
+ @pytest.mark.max_queries(2)
146
+ @pytest.mark.no_n_plus_one
147
+ def test_authors_declarative(client, db):
148
+ assert client.get("/api/authors?optimized=1").status_code == 200
149
+ ```
150
+
151
+ See [docs/testing-guardrails.md](https://github.com/duhanguler/flask-lens/blob/main/docs/testing-guardrails.md) for fixtures, custom thresholds, and failure reports.
152
+
153
+ ---
154
+
155
+ ## Custom Spans, Events & `Server-Timing`
156
+
157
+ Annotate business logic on the request waterfall with zero ceremony:
158
+
159
+ ```python
160
+ @app.post("/api/orders")
161
+ @lens.profile # Profile even when profile_mode="on_demand"
162
+ def create_order():
163
+ with lens.span("payment.authorize", provider="stripe") as meta:
164
+ charge = authorize_payment()
165
+ meta["charge_id"] = charge.id
166
+
167
+ lens.event("order.created", {"amount_cents": 4900})
168
+ return jsonify({"ok": True}), 201
169
+ ```
170
+
171
+ Every captured response also emits a standard W3C `Server-Timing` header so timings appear natively in Chrome DevTools:
172
+
173
+ ```http
174
+ Server-Timing: total;dur=10.90, sql;dur=0.12;desc="13 queries"
175
+ X-Lens-Request-Id: 24e3ed17d96c4a58
176
+ ```
177
+
178
+ ---
179
+
180
+ ## Flask CLI Integration
181
+
182
+ `flask-lens` registers a `flask lens` command group automatically:
183
+
184
+ ```bash
185
+ flask lens status # Active config, watched engines, stored counts
186
+ flask lens stats --limit 15 # Per-endpoint p50/p95/p99 latency, SQL & N+1 table
187
+ flask lens slow --limit 10 # Top normalized SQL fingerprints by total time
188
+ flask lens export report.json # Export full telemetry snapshot for bug reports
189
+ flask lens clear # Wipe stored ring-buffer telemetry
190
+ ```
191
+
192
+ ---
193
+
194
+ ## Measured Overhead Benchmarks
195
+
196
+ Measured locally with [`benchmarks/bench_overhead.py`](https://github.com/duhanguler/flask-lens/blob/main/benchmarks/bench_overhead.py) (CPython 3.13, macOS Apple Silicon, 300 iterations after 30 warmup iterations per scenario):
197
+
198
+ | Scenario | JSON Route (`/ping`) Mean | JSON Delta | SQLAlchemy Route (`/items`) Mean | SQLAlchemy Delta |
199
+ | :--- | ---: | ---: | ---: | ---: |
200
+ | Plain Flask (baseline) | `0.090 ms` | baseline | `0.202 ms` | baseline |
201
+ | `Lens(enabled=False)` | `0.084 ms` | `~0.000 ms` | `0.200 ms` | `~0.000 ms` |
202
+ | `Lens(storage="memory", profile_mode="off")` | `0.147 ms` | `+0.057 ms` | `0.375 ms` | `+0.172 ms` |
203
+ | `Lens(storage="sqlite", profile_mode="off")` | `0.249 ms` | `+0.159 ms` | `0.604 ms` | `+0.401 ms` |
204
+ | `Lens(storage="sqlite", profile_mode="always")` | `1.302 ms` | `+1.212 ms` | `6.339 ms` | `+6.137 ms` |
205
+
206
+ Reproduce on your hardware with `make bench`. For high-traffic staging runs, set `profile_mode="on_demand"` or `profile_mode="slow"` to keep request capture under **0.4 ms**.
207
+
208
+ ---
209
+
210
+ ## Architecture
211
+
212
+ ```mermaid
213
+ flowchart LR
214
+ Req["Flask HTTP Request"] --> Hooks["Lens Lifecycle Hooks<br/>(before / after / teardown / signals)"]
215
+ Hooks --> Ctx["ContextVar RequestContext"]
216
+ SQLA["SQLAlchemy Engine Events"] --> Ctx
217
+ HTTP["urllib3 / httpx Wrappers"] --> Ctx
218
+ Logs["Request-Scoped LogHandler"] --> Ctx
219
+ Prof["cProfile Collector"] --> Ctx
220
+ Ctx --> Analyzer["SQL Normalizer & N+1 Analyzer<br/>+ Secret Redactor"]
221
+ Analyzer --> Store["SQLite WAL / Memory Ring-Buffer"]
222
+ Analyzer --> SSE["SSE Broadcaster"]
223
+ Store --> BP["/__lens Blueprint<br/>(REST API + Embedded SPA)"]
224
+ SSE --> BP
225
+ ```
226
+
227
+ ---
228
+
229
+ ## Security & Production Guidance
230
+
231
+ - **Access Control:** Gate `/__lens` outside localhost using `authorize=lambda req: ...`.
232
+ - **Automatic Redaction:** Sensitive headers (`Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key`), JSON/form fields, SQL bind parameters, and exception locals are redacted to `[REDACTED]` by default before persistence.
233
+ - **Safe `EXPLAIN`:** Strictly limited to single, read-only `SELECT` statements; mutating DML/DDL and multi-statement queries are rejected.
234
+ - **Safe Replay:** Restricted to relative application paths; `/__lens` routes and external URLs are rejected to prevent recursion and SSRF.
235
+
236
+ Read [docs/configuration.md](https://github.com/duhanguler/flask-lens/blob/main/docs/configuration.md) and [SECURITY.md](https://github.com/duhanguler/flask-lens/blob/main/SECURITY.md) for full details.
237
+
238
+ ---
239
+
240
+ ## Development
241
+
242
+ ```bash
243
+ make install # Create .venv via uv and install dev dependencies
244
+ make check # ruff lint + format check + mypy --strict + pytest coverage
245
+ make bench # Run reproducible WSGI overhead benchmarks
246
+ make build # Build wheel & sdist via hatchling
247
+ ```
248
+
249
+ ## License
250
+
251
+ MIT — see [LICENSE](https://github.com/duhanguler/flask-lens/blob/main/LICENSE).