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.
- flask_lens-0.2.0/.gitignore +27 -0
- flask_lens-0.2.0/CHANGELOG.md +42 -0
- flask_lens-0.2.0/LICENSE +21 -0
- flask_lens-0.2.0/PKG-INFO +304 -0
- flask_lens-0.2.0/README.md +251 -0
- flask_lens-0.2.0/benchmarks/bench_overhead.py +169 -0
- flask_lens-0.2.0/docs/assets/compare-diff.png +0 -0
- flask_lens-0.2.0/docs/assets/exception-inspector.png +0 -0
- flask_lens-0.2.0/docs/assets/flamegraph.png +0 -0
- flask_lens-0.2.0/docs/assets/overview-n1.png +0 -0
- flask_lens-0.2.0/docs/assets/sql-explain.png +0 -0
- flask_lens-0.2.0/docs/configuration.md +62 -0
- flask_lens-0.2.0/docs/testing-guardrails.md +87 -0
- flask_lens-0.2.0/examples/bookstore_app.py +270 -0
- flask_lens-0.2.0/examples/minimal_app.py +21 -0
- flask_lens-0.2.0/pyproject.toml +145 -0
- flask_lens-0.2.0/src/flask_lens/__init__.py +56 -0
- flask_lens-0.2.0/src/flask_lens/blueprint.py +261 -0
- flask_lens-0.2.0/src/flask_lens/cli.py +130 -0
- flask_lens-0.2.0/src/flask_lens/collectors/__init__.py +43 -0
- flask_lens-0.2.0/src/flask_lens/collectors/context.py +126 -0
- flask_lens-0.2.0/src/flask_lens/collectors/exceptions.py +79 -0
- flask_lens-0.2.0/src/flask_lens/collectors/http_outgoing.py +267 -0
- flask_lens-0.2.0/src/flask_lens/collectors/logging_handler.py +68 -0
- flask_lens-0.2.0/src/flask_lens/collectors/profiler.py +280 -0
- flask_lens-0.2.0/src/flask_lens/config.py +210 -0
- flask_lens-0.2.0/src/flask_lens/extension.py +713 -0
- flask_lens-0.2.0/src/flask_lens/models.py +487 -0
- flask_lens-0.2.0/src/flask_lens/py.typed +0 -0
- flask_lens-0.2.0/src/flask_lens/pytest_plugin.py +177 -0
- flask_lens-0.2.0/src/flask_lens/redaction.py +276 -0
- flask_lens-0.2.0/src/flask_lens/sql/__init__.py +38 -0
- flask_lens-0.2.0/src/flask_lens/sql/analyzer.py +133 -0
- flask_lens-0.2.0/src/flask_lens/sql/explain.py +196 -0
- flask_lens-0.2.0/src/flask_lens/sql/listener.py +454 -0
- flask_lens-0.2.0/src/flask_lens/sql/normalizer.py +184 -0
- flask_lens-0.2.0/src/flask_lens/storage/__init__.py +21 -0
- flask_lens-0.2.0/src/flask_lens/storage/base.py +154 -0
- flask_lens-0.2.0/src/flask_lens/storage/memory.py +261 -0
- flask_lens-0.2.0/src/flask_lens/storage/sqlite.py +528 -0
- flask_lens-0.2.0/src/flask_lens/testing.py +189 -0
- flask_lens-0.2.0/src/flask_lens/ui/__init__.py +1 -0
- flask_lens-0.2.0/src/flask_lens/ui/app.js +1829 -0
- flask_lens-0.2.0/src/flask_lens/ui/index.html +269 -0
- flask_lens-0.2.0/src/flask_lens/ui/styles.css +1525 -0
- flask_lens-0.2.0/tests/__init__.py +0 -0
- flask_lens-0.2.0/tests/conftest.py +146 -0
- flask_lens-0.2.0/tests/test_blueprint_replay_and_sse.py +149 -0
- flask_lens-0.2.0/tests/test_bug_hunt_regressions.py +411 -0
- flask_lens-0.2.0/tests/test_cli.py +50 -0
- flask_lens-0.2.0/tests/test_edge_cases.py +314 -0
- flask_lens-0.2.0/tests/test_extension_and_sqlalchemy.py +221 -0
- flask_lens-0.2.0/tests/test_outgoing_http.py +114 -0
- flask_lens-0.2.0/tests/test_redaction.py +92 -0
- flask_lens-0.2.0/tests/test_sql_normalizer_and_analyzer.py +145 -0
- flask_lens-0.2.0/tests/test_storage.py +198 -0
- 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`).
|
flask_lens-0.2.0/LICENSE
ADDED
|
@@ -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
|
+
[](https://github.com/duhanguler/flask-lens/actions/workflows/ci.yml)
|
|
57
|
+
[](https://pypi.org/project/flask-lens/)
|
|
58
|
+
[](https://www.python.org/downloads/)
|
|
59
|
+
[](https://github.com/duhanguler/flask-lens/blob/main/src/flask_lens/py.typed)
|
|
60
|
+
[](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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+
[](https://github.com/duhanguler/flask-lens/actions/workflows/ci.yml)
|
|
4
|
+
[](https://pypi.org/project/flask-lens/)
|
|
5
|
+
[](https://www.python.org/downloads/)
|
|
6
|
+
[](https://github.com/duhanguler/flask-lens/blob/main/src/flask_lens/py.typed)
|
|
7
|
+
[](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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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).
|