flask-lens 0.2.0__py3-none-any.whl
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/__init__.py +56 -0
- flask_lens/blueprint.py +261 -0
- flask_lens/cli.py +130 -0
- flask_lens/collectors/__init__.py +43 -0
- flask_lens/collectors/context.py +126 -0
- flask_lens/collectors/exceptions.py +79 -0
- flask_lens/collectors/http_outgoing.py +267 -0
- flask_lens/collectors/logging_handler.py +68 -0
- flask_lens/collectors/profiler.py +280 -0
- flask_lens/config.py +210 -0
- flask_lens/extension.py +713 -0
- flask_lens/models.py +487 -0
- flask_lens/py.typed +0 -0
- flask_lens/pytest_plugin.py +177 -0
- flask_lens/redaction.py +276 -0
- flask_lens/sql/__init__.py +38 -0
- flask_lens/sql/analyzer.py +133 -0
- flask_lens/sql/explain.py +196 -0
- flask_lens/sql/listener.py +454 -0
- flask_lens/sql/normalizer.py +184 -0
- flask_lens/storage/__init__.py +21 -0
- flask_lens/storage/base.py +154 -0
- flask_lens/storage/memory.py +261 -0
- flask_lens/storage/sqlite.py +528 -0
- flask_lens/testing.py +189 -0
- flask_lens/ui/__init__.py +1 -0
- flask_lens/ui/app.js +1829 -0
- flask_lens/ui/index.html +269 -0
- flask_lens/ui/styles.css +1525 -0
- flask_lens-0.2.0.dist-info/METADATA +304 -0
- flask_lens-0.2.0.dist-info/RECORD +34 -0
- flask_lens-0.2.0.dist-info/WHEEL +4 -0
- flask_lens-0.2.0.dist-info/entry_points.txt +5 -0
- flask_lens-0.2.0.dist-info/licenses/LICENSE +21 -0
flask_lens/__init__.py
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
"""flask-lens: Real-time observability, SQL/N+1 profiler, flamegraph, and pytest guardrails for Flask."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from flask_lens.collectors.context import event, span
|
|
6
|
+
from flask_lens.config import LensConfig
|
|
7
|
+
from flask_lens.extension import Lens, LensState
|
|
8
|
+
from flask_lens.models import (
|
|
9
|
+
CapturedRequest,
|
|
10
|
+
CustomSpan,
|
|
11
|
+
ExceptionInfo,
|
|
12
|
+
LogEntry,
|
|
13
|
+
NPlusOneGroup,
|
|
14
|
+
OutgoingHTTP,
|
|
15
|
+
ProfileData,
|
|
16
|
+
SQLQuery,
|
|
17
|
+
StackFrame,
|
|
18
|
+
)
|
|
19
|
+
from flask_lens.storage.memory import MemoryStorage
|
|
20
|
+
from flask_lens.storage.sqlite import SQLiteStorage
|
|
21
|
+
from flask_lens.testing import (
|
|
22
|
+
QueryAssertionError,
|
|
23
|
+
QueryCapture,
|
|
24
|
+
assert_max_queries,
|
|
25
|
+
assert_no_n_plus_one,
|
|
26
|
+
assert_num_queries,
|
|
27
|
+
capture_queries,
|
|
28
|
+
)
|
|
29
|
+
|
|
30
|
+
__version__ = "0.2.0"
|
|
31
|
+
|
|
32
|
+
__all__ = [
|
|
33
|
+
"CapturedRequest",
|
|
34
|
+
"CustomSpan",
|
|
35
|
+
"ExceptionInfo",
|
|
36
|
+
"Lens",
|
|
37
|
+
"LensConfig",
|
|
38
|
+
"LensState",
|
|
39
|
+
"LogEntry",
|
|
40
|
+
"MemoryStorage",
|
|
41
|
+
"NPlusOneGroup",
|
|
42
|
+
"OutgoingHTTP",
|
|
43
|
+
"ProfileData",
|
|
44
|
+
"QueryAssertionError",
|
|
45
|
+
"QueryCapture",
|
|
46
|
+
"SQLQuery",
|
|
47
|
+
"SQLiteStorage",
|
|
48
|
+
"StackFrame",
|
|
49
|
+
"__version__",
|
|
50
|
+
"assert_max_queries",
|
|
51
|
+
"assert_no_n_plus_one",
|
|
52
|
+
"assert_num_queries",
|
|
53
|
+
"capture_queries",
|
|
54
|
+
"event",
|
|
55
|
+
"span",
|
|
56
|
+
]
|
flask_lens/blueprint.py
ADDED
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
"""Flask Blueprint serving the embedded Lens UI and JSON/SSE telemetry API."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
import os
|
|
7
|
+
import queue
|
|
8
|
+
from collections.abc import Iterator
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
from flask import Blueprint, Response, abort, current_app, jsonify, request, send_from_directory
|
|
12
|
+
|
|
13
|
+
from flask_lens.extension import STREAM_STOP, LensState
|
|
14
|
+
from flask_lens.storage.base import RequestFilter, compute_request_diff
|
|
15
|
+
|
|
16
|
+
_UI_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "ui")
|
|
17
|
+
_ALLOWED_UI_ASSETS: frozenset[str] = frozenset({"styles.css", "app.js"})
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def _get_state() -> LensState:
|
|
21
|
+
state: LensState | None = current_app.extensions.get("lens")
|
|
22
|
+
if state is None:
|
|
23
|
+
raise RuntimeError("flask-lens is not initialized on this Flask application.")
|
|
24
|
+
return state
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def create_lens_blueprint() -> Blueprint:
|
|
28
|
+
"""Create the ``flask_lens`` Blueprint mounted at ``config.url_prefix``."""
|
|
29
|
+
bp = Blueprint("flask_lens", __name__)
|
|
30
|
+
|
|
31
|
+
@bp.before_request
|
|
32
|
+
def _authorize() -> Response | None:
|
|
33
|
+
state = _get_state()
|
|
34
|
+
auth_fn = state.config.authorize
|
|
35
|
+
if auth_fn is not None and not auth_fn(request):
|
|
36
|
+
if request.path.endswith("/api") or "/api/" in request.path:
|
|
37
|
+
resp = jsonify({"error": "Forbidden", "message": "Access to flask-lens denied."})
|
|
38
|
+
resp.status_code = 403
|
|
39
|
+
return resp
|
|
40
|
+
return Response(
|
|
41
|
+
"<h1>403 Forbidden</h1><p>Access to flask-lens is restricted.</p>",
|
|
42
|
+
status=403,
|
|
43
|
+
mimetype="text/html",
|
|
44
|
+
)
|
|
45
|
+
return None
|
|
46
|
+
|
|
47
|
+
# ── Embedded UI routes ────────────────────────────────────────────────
|
|
48
|
+
|
|
49
|
+
@bp.route("/")
|
|
50
|
+
@bp.route("/requests/<request_id>")
|
|
51
|
+
@bp.route("/endpoints")
|
|
52
|
+
@bp.route("/sql")
|
|
53
|
+
@bp.route("/exceptions")
|
|
54
|
+
@bp.route("/compare")
|
|
55
|
+
def ui_index(request_id: str | None = None) -> Response:
|
|
56
|
+
state = _get_state()
|
|
57
|
+
index_path = os.path.join(_UI_DIR, "index.html")
|
|
58
|
+
with open(index_path, encoding="utf-8") as fh:
|
|
59
|
+
html = fh.read()
|
|
60
|
+
base_url = state.config.url_prefix
|
|
61
|
+
html = html.replace("__LENS_BASE_URL__", base_url)
|
|
62
|
+
return Response(html, mimetype="text/html; charset=utf-8")
|
|
63
|
+
|
|
64
|
+
@bp.route("/assets/<path:filename>")
|
|
65
|
+
def ui_asset(filename: str) -> Response:
|
|
66
|
+
if filename not in _ALLOWED_UI_ASSETS:
|
|
67
|
+
abort(404)
|
|
68
|
+
return send_from_directory(_UI_DIR, filename)
|
|
69
|
+
|
|
70
|
+
# ── Telemetry REST API ────────────────────────────────────────────────
|
|
71
|
+
|
|
72
|
+
@bp.get("/api/health")
|
|
73
|
+
def api_health() -> Response:
|
|
74
|
+
from flask_lens import __version__
|
|
75
|
+
|
|
76
|
+
state = _get_state()
|
|
77
|
+
cfg = state.config
|
|
78
|
+
return jsonify(
|
|
79
|
+
{
|
|
80
|
+
"status": "ok",
|
|
81
|
+
"version": __version__,
|
|
82
|
+
"url_prefix": cfg.url_prefix,
|
|
83
|
+
"storage": cfg.storage,
|
|
84
|
+
"profile_mode": cfg.profile_mode,
|
|
85
|
+
"slow_query_ms": cfg.slow_query_ms,
|
|
86
|
+
"n_plus_one_threshold": cfg.n_plus_one_threshold,
|
|
87
|
+
"allow_explain": cfg.allow_explain,
|
|
88
|
+
"allow_replay": cfg.allow_replay,
|
|
89
|
+
"watched_engines": sorted(state.watched_engines.keys()),
|
|
90
|
+
}
|
|
91
|
+
)
|
|
92
|
+
|
|
93
|
+
@bp.get("/api/overview")
|
|
94
|
+
def api_overview() -> Response:
|
|
95
|
+
state = _get_state()
|
|
96
|
+
return jsonify(state.storage.overview_stats())
|
|
97
|
+
|
|
98
|
+
@bp.get("/api/requests")
|
|
99
|
+
def api_list_requests() -> Response:
|
|
100
|
+
state = _get_state()
|
|
101
|
+
limit = _parse_int(request.args.get("limit"), default=100, minimum=1, maximum=500)
|
|
102
|
+
offset = _parse_int(request.args.get("offset"), default=0, minimum=0, maximum=100_000)
|
|
103
|
+
min_ms_raw = request.args.get("min_ms")
|
|
104
|
+
min_ms: float | None = None
|
|
105
|
+
if min_ms_raw:
|
|
106
|
+
try:
|
|
107
|
+
min_ms = float(min_ms_raw)
|
|
108
|
+
except ValueError:
|
|
109
|
+
min_ms = None
|
|
110
|
+
|
|
111
|
+
flt = RequestFilter(
|
|
112
|
+
limit=limit,
|
|
113
|
+
offset=offset,
|
|
114
|
+
method=request.args.get("method") or None,
|
|
115
|
+
status_group=request.args.get("status") or None,
|
|
116
|
+
search=request.args.get("q") or None,
|
|
117
|
+
only_n_plus_one=_parse_bool(request.args.get("n_plus_one")),
|
|
118
|
+
only_slow=_parse_bool(request.args.get("slow")),
|
|
119
|
+
only_errors=_parse_bool(request.args.get("errors")),
|
|
120
|
+
min_duration_ms=min_ms,
|
|
121
|
+
)
|
|
122
|
+
items, total = state.storage.list_requests(flt)
|
|
123
|
+
return jsonify({"items": items, "total": total, "limit": limit, "offset": offset})
|
|
124
|
+
|
|
125
|
+
@bp.get("/api/requests/<request_id>")
|
|
126
|
+
def api_get_request(request_id: str) -> tuple[Response, int] | Response:
|
|
127
|
+
state = _get_state()
|
|
128
|
+
captured = state.storage.get(request_id)
|
|
129
|
+
if captured is None:
|
|
130
|
+
return jsonify({"error": "Not found", "request_id": request_id}), 404
|
|
131
|
+
return jsonify(captured.to_dict())
|
|
132
|
+
|
|
133
|
+
@bp.post("/api/requests/<request_id>/explain/<query_id>")
|
|
134
|
+
def api_explain_query(request_id: str, query_id: str) -> tuple[Response, int] | Response:
|
|
135
|
+
state = _get_state()
|
|
136
|
+
result = state.explain_query(request_id, query_id)
|
|
137
|
+
status = 200 if result.error is None else 400
|
|
138
|
+
return jsonify(result.to_dict()), status
|
|
139
|
+
|
|
140
|
+
@bp.post("/api/replay")
|
|
141
|
+
def api_replay() -> tuple[Response, int] | Response:
|
|
142
|
+
state = _get_state()
|
|
143
|
+
payload: dict[str, Any] = request.get_json(silent=True) or {}
|
|
144
|
+
method = str(payload.get("method", "GET"))
|
|
145
|
+
path = str(payload.get("path", "/"))
|
|
146
|
+
headers = payload.get("headers")
|
|
147
|
+
body = payload.get("body")
|
|
148
|
+
original_id = payload.get("original_request_id")
|
|
149
|
+
|
|
150
|
+
if headers is not None and not isinstance(headers, dict):
|
|
151
|
+
return jsonify({"error": "headers must be a JSON object"}), 400
|
|
152
|
+
if body is not None and not isinstance(body, str):
|
|
153
|
+
body = json.dumps(body)
|
|
154
|
+
|
|
155
|
+
try:
|
|
156
|
+
result = state.replay_request(
|
|
157
|
+
method=method,
|
|
158
|
+
path=path,
|
|
159
|
+
headers=headers,
|
|
160
|
+
body=body,
|
|
161
|
+
original_request_id=str(original_id) if original_id else None,
|
|
162
|
+
)
|
|
163
|
+
except PermissionError as exc:
|
|
164
|
+
return jsonify({"error": str(exc)}), 403
|
|
165
|
+
except ValueError as exc:
|
|
166
|
+
return jsonify({"error": str(exc)}), 400
|
|
167
|
+
return jsonify(result)
|
|
168
|
+
|
|
169
|
+
@bp.get("/api/compare")
|
|
170
|
+
def api_compare() -> tuple[Response, int] | Response:
|
|
171
|
+
state = _get_state()
|
|
172
|
+
baseline_id = request.args.get("baseline", "").strip()
|
|
173
|
+
candidate_id = request.args.get("candidate", "").strip()
|
|
174
|
+
if not baseline_id or not candidate_id:
|
|
175
|
+
return jsonify(
|
|
176
|
+
{"error": "Both 'baseline' and 'candidate' query parameters are required."}
|
|
177
|
+
), 400
|
|
178
|
+
|
|
179
|
+
baseline = state.storage.get(baseline_id)
|
|
180
|
+
candidate = state.storage.get(candidate_id)
|
|
181
|
+
if baseline is None:
|
|
182
|
+
return jsonify({"error": f"Baseline request {baseline_id!r} not found."}), 404
|
|
183
|
+
if candidate is None:
|
|
184
|
+
return jsonify({"error": f"Candidate request {candidate_id!r} not found."}), 404
|
|
185
|
+
return jsonify(compute_request_diff(baseline, candidate))
|
|
186
|
+
|
|
187
|
+
@bp.get("/api/endpoints")
|
|
188
|
+
def api_endpoints() -> Response:
|
|
189
|
+
state = _get_state()
|
|
190
|
+
return jsonify({"items": state.storage.endpoint_stats()})
|
|
191
|
+
|
|
192
|
+
@bp.get("/api/sql")
|
|
193
|
+
def api_sql() -> Response:
|
|
194
|
+
state = _get_state()
|
|
195
|
+
limit = _parse_int(request.args.get("limit"), default=100, minimum=1, maximum=500)
|
|
196
|
+
return jsonify({"items": state.storage.sql_stats(limit=limit)})
|
|
197
|
+
|
|
198
|
+
@bp.get("/api/exceptions")
|
|
199
|
+
def api_exceptions() -> Response:
|
|
200
|
+
state = _get_state()
|
|
201
|
+
return jsonify({"items": state.storage.exception_groups()})
|
|
202
|
+
|
|
203
|
+
@bp.route("/api/clear", methods=["POST", "DELETE"])
|
|
204
|
+
@bp.delete("/api/requests")
|
|
205
|
+
def api_clear() -> Response:
|
|
206
|
+
state = _get_state()
|
|
207
|
+
deleted = state.storage.clear()
|
|
208
|
+
return jsonify({"cleared": deleted})
|
|
209
|
+
|
|
210
|
+
@bp.get("/api/stream")
|
|
211
|
+
def api_stream() -> Response:
|
|
212
|
+
state = _get_state()
|
|
213
|
+
max_events = _parse_int(request.args.get("max_events"), default=0, minimum=0, maximum=1000)
|
|
214
|
+
sub_queue = state.broadcaster.subscribe()
|
|
215
|
+
|
|
216
|
+
def _event_stream() -> Iterator[str]:
|
|
217
|
+
sent = 0
|
|
218
|
+
try:
|
|
219
|
+
yield "event: connected\ndata: {}\n\n"
|
|
220
|
+
while True:
|
|
221
|
+
if max_events > 0 and sent >= max_events:
|
|
222
|
+
break
|
|
223
|
+
try:
|
|
224
|
+
item = sub_queue.get(timeout=15.0)
|
|
225
|
+
if item is STREAM_STOP:
|
|
226
|
+
break
|
|
227
|
+
payload = json.dumps(item, ensure_ascii=False)
|
|
228
|
+
yield f"event: request\ndata: {payload}\n\n"
|
|
229
|
+
sent += 1
|
|
230
|
+
except queue.Empty:
|
|
231
|
+
yield ": keepalive\n\n"
|
|
232
|
+
if max_events > 0:
|
|
233
|
+
break
|
|
234
|
+
finally:
|
|
235
|
+
state.broadcaster.unsubscribe(sub_queue)
|
|
236
|
+
|
|
237
|
+
return Response(
|
|
238
|
+
_event_stream(),
|
|
239
|
+
mimetype="text/event-stream",
|
|
240
|
+
headers={
|
|
241
|
+
"Cache-Control": "no-cache",
|
|
242
|
+
"X-Accel-Buffering": "no",
|
|
243
|
+
"Connection": "keep-alive",
|
|
244
|
+
},
|
|
245
|
+
)
|
|
246
|
+
|
|
247
|
+
return bp
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
def _parse_int(raw: str | None, *, default: int, minimum: int, maximum: int) -> int:
|
|
251
|
+
if raw is None:
|
|
252
|
+
return default
|
|
253
|
+
try:
|
|
254
|
+
val = int(raw)
|
|
255
|
+
except ValueError:
|
|
256
|
+
return default
|
|
257
|
+
return max(minimum, min(maximum, val))
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def _parse_bool(raw: str | None) -> bool:
|
|
261
|
+
return (raw or "").strip().lower() in {"1", "true", "yes", "on"}
|
flask_lens/cli.py
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
"""Flask CLI commands exposed under ``flask lens ...``."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
import click
|
|
9
|
+
from flask import current_app
|
|
10
|
+
from flask.cli import with_appcontext
|
|
11
|
+
|
|
12
|
+
from flask_lens.extension import LensState
|
|
13
|
+
from flask_lens.storage.base import RequestFilter
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def _require_state() -> LensState:
|
|
17
|
+
state: LensState | None = current_app.extensions.get("lens")
|
|
18
|
+
if state is None:
|
|
19
|
+
raise click.ClickException("flask-lens is not initialized on this Flask application.")
|
|
20
|
+
return state
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@click.group("lens")
|
|
24
|
+
def lens_cli() -> None:
|
|
25
|
+
"""Inspect and manage flask-lens telemetry."""
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
@lens_cli.command("status")
|
|
29
|
+
@with_appcontext
|
|
30
|
+
def lens_status() -> None:
|
|
31
|
+
"""Show active flask-lens configuration and storage summary."""
|
|
32
|
+
state = _require_state()
|
|
33
|
+
cfg = state.config
|
|
34
|
+
stats = state.storage.overview_stats()
|
|
35
|
+
click.echo(f"flask-lens enabled : {cfg.enabled}")
|
|
36
|
+
click.echo(f"Dashboard URL prefix : {cfg.url_prefix}")
|
|
37
|
+
click.echo(
|
|
38
|
+
f"Storage backend : {cfg.storage} ({cfg.db_path if cfg.storage == 'sqlite' else 'in-memory'})"
|
|
39
|
+
)
|
|
40
|
+
click.echo(f"Profile mode : {cfg.profile_mode}")
|
|
41
|
+
click.echo(
|
|
42
|
+
f"Watched engines : {', '.join(sorted(state.watched_engines.keys())) or 'none'}"
|
|
43
|
+
)
|
|
44
|
+
click.echo(f"Stored requests : {stats['total_requests']} / {cfg.max_requests}")
|
|
45
|
+
click.echo(f"N+1 alerts : {stats['n_plus_one_requests']}")
|
|
46
|
+
click.echo(f"Captured exceptions : {stats['exception_count']}")
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
@lens_cli.command("stats")
|
|
50
|
+
@click.option("--limit", default=15, show_default=True, type=int, help="Maximum endpoints to list.")
|
|
51
|
+
@with_appcontext
|
|
52
|
+
def lens_stats(limit: int) -> None:
|
|
53
|
+
"""Print latency and SQL query analytics grouped by endpoint."""
|
|
54
|
+
state = _require_state()
|
|
55
|
+
endpoints = state.storage.endpoint_stats()[:limit]
|
|
56
|
+
if not endpoints:
|
|
57
|
+
click.echo("No captured requests yet.")
|
|
58
|
+
return
|
|
59
|
+
click.echo(
|
|
60
|
+
f"{'METHOD':<7} {'ROUTE':<32} {'REQS':>5} {'P50':>8} {'P95':>8} {'SQL':>6} {'N+1':>5} {'ERR%':>6}"
|
|
61
|
+
)
|
|
62
|
+
click.echo("-" * 84)
|
|
63
|
+
for ep in endpoints:
|
|
64
|
+
route = str(ep["route"])
|
|
65
|
+
if len(route) > 31:
|
|
66
|
+
route = route[:28] + "..."
|
|
67
|
+
click.echo(
|
|
68
|
+
f"{ep['method']:<7} {route:<32} {ep['count']:>5} "
|
|
69
|
+
f"{ep['p50_ms']:>7.1f}m {ep['p95_ms']:>7.1f}m "
|
|
70
|
+
f"{ep['avg_sql']:>6.1f} {ep['n_plus_one_hits']:>5} {ep['error_rate']:>5.1f}%"
|
|
71
|
+
)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
@lens_cli.command("slow")
|
|
75
|
+
@click.option(
|
|
76
|
+
"--limit", default=10, show_default=True, type=int, help="Maximum slow queries to list."
|
|
77
|
+
)
|
|
78
|
+
@with_appcontext
|
|
79
|
+
def lens_slow(limit: int) -> None:
|
|
80
|
+
"""List top normalized SQL fingerprints ordered by total execution time."""
|
|
81
|
+
state = _require_state()
|
|
82
|
+
rows = state.storage.sql_stats(limit=limit)
|
|
83
|
+
if not rows:
|
|
84
|
+
click.echo("No captured SQL queries yet.")
|
|
85
|
+
return
|
|
86
|
+
for idx, row in enumerate(rows, start=1):
|
|
87
|
+
n1_tag = f" [N+1 x{row['n_plus_one_hits']}]" if row["n_plus_one_hits"] else ""
|
|
88
|
+
click.echo(
|
|
89
|
+
f"{idx:>2}. {row['total_ms']:>7.2f}ms total | avg {row['avg_ms']:.2f}ms | "
|
|
90
|
+
f"{row['calls']} calls{n1_tag}"
|
|
91
|
+
)
|
|
92
|
+
click.echo(f" {row['normalized_sql'][:110]}")
|
|
93
|
+
if row["sample_call_site"]:
|
|
94
|
+
click.echo(f" at {row['sample_call_site']}")
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
@lens_cli.command("clear")
|
|
98
|
+
@with_appcontext
|
|
99
|
+
def lens_clear() -> None:
|
|
100
|
+
"""Delete all stored telemetry records."""
|
|
101
|
+
state = _require_state()
|
|
102
|
+
count = state.storage.clear()
|
|
103
|
+
click.echo(f"Cleared {count} captured request(s).")
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
@lens_cli.command("export")
|
|
107
|
+
@click.argument("output", type=click.Path(dir_okay=False, writable=True))
|
|
108
|
+
@click.option(
|
|
109
|
+
"--limit", default=200, show_default=True, type=int, help="Maximum requests to export."
|
|
110
|
+
)
|
|
111
|
+
@with_appcontext
|
|
112
|
+
def lens_export(output: str, limit: int) -> None:
|
|
113
|
+
"""Export captured requests and full SQL/profile telemetry to a JSON file."""
|
|
114
|
+
state = _require_state()
|
|
115
|
+
summaries, total = state.storage.list_requests(RequestFilter(limit=limit))
|
|
116
|
+
full_records: list[dict[str, Any]] = []
|
|
117
|
+
for item in summaries:
|
|
118
|
+
rec = state.storage.get(item["id"])
|
|
119
|
+
if rec is not None:
|
|
120
|
+
full_records.append(rec.to_dict())
|
|
121
|
+
|
|
122
|
+
payload = {
|
|
123
|
+
"total_stored": total,
|
|
124
|
+
"exported": len(full_records),
|
|
125
|
+
"overview": state.storage.overview_stats(),
|
|
126
|
+
"requests": full_records,
|
|
127
|
+
}
|
|
128
|
+
with open(output, "w", encoding="utf-8") as fh:
|
|
129
|
+
json.dump(payload, fh, indent=2, ensure_ascii=False)
|
|
130
|
+
click.echo(f"Exported {len(full_records)} request(s) to {output}.")
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
"""Request-scoped collectors for SQL, profiling, outgoing HTTP, logs, and exceptions."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from flask_lens.collectors.context import (
|
|
6
|
+
RequestContext,
|
|
7
|
+
event,
|
|
8
|
+
get_active_request,
|
|
9
|
+
is_capture_suspended,
|
|
10
|
+
reset_active_request,
|
|
11
|
+
set_active_request,
|
|
12
|
+
span,
|
|
13
|
+
suspend_capture,
|
|
14
|
+
)
|
|
15
|
+
from flask_lens.collectors.exceptions import capture_exception
|
|
16
|
+
from flask_lens.collectors.http_outgoing import (
|
|
17
|
+
install_http_hooks,
|
|
18
|
+
uninstall_http_hooks,
|
|
19
|
+
)
|
|
20
|
+
from flask_lens.collectors.logging_handler import (
|
|
21
|
+
LensLogHandler,
|
|
22
|
+
install_log_handler,
|
|
23
|
+
uninstall_log_handler,
|
|
24
|
+
)
|
|
25
|
+
from flask_lens.collectors.profiler import RequestProfiler
|
|
26
|
+
|
|
27
|
+
__all__ = [
|
|
28
|
+
"LensLogHandler",
|
|
29
|
+
"RequestContext",
|
|
30
|
+
"RequestProfiler",
|
|
31
|
+
"capture_exception",
|
|
32
|
+
"event",
|
|
33
|
+
"get_active_request",
|
|
34
|
+
"install_http_hooks",
|
|
35
|
+
"install_log_handler",
|
|
36
|
+
"is_capture_suspended",
|
|
37
|
+
"reset_active_request",
|
|
38
|
+
"set_active_request",
|
|
39
|
+
"span",
|
|
40
|
+
"suspend_capture",
|
|
41
|
+
"uninstall_http_hooks",
|
|
42
|
+
"uninstall_log_handler",
|
|
43
|
+
]
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
"""Thread-safe and async-safe per-request collector state via ContextVar."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import contextlib
|
|
6
|
+
import contextvars
|
|
7
|
+
import time
|
|
8
|
+
from collections.abc import Iterator
|
|
9
|
+
from dataclasses import dataclass, field
|
|
10
|
+
from typing import TYPE_CHECKING, Any
|
|
11
|
+
|
|
12
|
+
from flask_lens.models import CustomSpan, ExceptionInfo, LogEntry, OutgoingHTTP, SQLQuery
|
|
13
|
+
|
|
14
|
+
if TYPE_CHECKING:
|
|
15
|
+
from flask_lens.collectors.profiler import RequestProfiler
|
|
16
|
+
from flask_lens.config import LensConfig
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
@dataclass
|
|
20
|
+
class RequestContext:
|
|
21
|
+
"""Mutable collector state bound to the lifetime of a single Flask request."""
|
|
22
|
+
|
|
23
|
+
request_id: str
|
|
24
|
+
config: LensConfig
|
|
25
|
+
start_time: float
|
|
26
|
+
start_perf: float
|
|
27
|
+
is_replay: bool = False
|
|
28
|
+
replayed_from: str | None = None
|
|
29
|
+
force_profile: bool = False
|
|
30
|
+
profiler: RequestProfiler | None = None
|
|
31
|
+
watched_engine_ids: set[str] = field(default_factory=set)
|
|
32
|
+
|
|
33
|
+
sql_queries: list[SQLQuery] = field(default_factory=list)
|
|
34
|
+
outgoing_http: list[OutgoingHTTP] = field(default_factory=list)
|
|
35
|
+
logs: list[LogEntry] = field(default_factory=list)
|
|
36
|
+
spans: list[CustomSpan] = field(default_factory=list)
|
|
37
|
+
templates: list[str] = field(default_factory=list)
|
|
38
|
+
exception: ExceptionInfo | None = None
|
|
39
|
+
|
|
40
|
+
def elapsed_ms(self) -> float:
|
|
41
|
+
return round((time.perf_counter() - self.start_perf) * 1000.0, 3)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
_ACTIVE_REQUEST: contextvars.ContextVar[RequestContext | None] = contextvars.ContextVar(
|
|
45
|
+
"flask_lens_active_request",
|
|
46
|
+
default=None,
|
|
47
|
+
)
|
|
48
|
+
_SUSPENDED: contextvars.ContextVar[int] = contextvars.ContextVar(
|
|
49
|
+
"flask_lens_capture_suspended",
|
|
50
|
+
default=0,
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def get_active_request() -> RequestContext | None:
|
|
55
|
+
return _ACTIVE_REQUEST.get()
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def set_active_request(ctx: RequestContext | None) -> contextvars.Token[RequestContext | None]:
|
|
59
|
+
return _ACTIVE_REQUEST.set(ctx)
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def reset_active_request(token: contextvars.Token[RequestContext | None]) -> None:
|
|
63
|
+
_ACTIVE_REQUEST.reset(token)
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def is_capture_suspended() -> bool:
|
|
67
|
+
return _SUSPENDED.get() > 0
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
@contextlib.contextmanager
|
|
71
|
+
def suspend_capture() -> Iterator[None]:
|
|
72
|
+
"""Temporarily pause SQL/HTTP/log collection (used internally by EXPLAIN & storage)."""
|
|
73
|
+
token = _SUSPENDED.set(_SUSPENDED.get() + 1)
|
|
74
|
+
try:
|
|
75
|
+
yield
|
|
76
|
+
finally:
|
|
77
|
+
_SUSPENDED.reset(token)
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
@contextlib.contextmanager
|
|
81
|
+
def span(name: str, **metadata: Any) -> Iterator[dict[str, Any]]:
|
|
82
|
+
"""Record a timed custom span on the current request's waterfall timeline.
|
|
83
|
+
|
|
84
|
+
Usage::
|
|
85
|
+
|
|
86
|
+
with lens.span("stripe.charge", customer_id=42) as meta:
|
|
87
|
+
result = charge_customer()
|
|
88
|
+
meta["status"] = result.status
|
|
89
|
+
"""
|
|
90
|
+
ctx = get_active_request()
|
|
91
|
+
meta: dict[str, Any] = dict(metadata)
|
|
92
|
+
if ctx is None:
|
|
93
|
+
yield meta
|
|
94
|
+
return
|
|
95
|
+
|
|
96
|
+
start_offset = ctx.elapsed_ms()
|
|
97
|
+
start_perf = time.perf_counter()
|
|
98
|
+
try:
|
|
99
|
+
yield meta
|
|
100
|
+
finally:
|
|
101
|
+
duration_ms = round((time.perf_counter() - start_perf) * 1000.0, 3)
|
|
102
|
+
ctx.spans.append(
|
|
103
|
+
CustomSpan(
|
|
104
|
+
name=name,
|
|
105
|
+
kind="span",
|
|
106
|
+
offset_ms=start_offset,
|
|
107
|
+
duration_ms=duration_ms,
|
|
108
|
+
metadata=meta,
|
|
109
|
+
)
|
|
110
|
+
)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def event(name: str, metadata: dict[str, Any] | None = None) -> None:
|
|
114
|
+
"""Record an instantaneous custom event marker on the current request."""
|
|
115
|
+
ctx = get_active_request()
|
|
116
|
+
if ctx is None:
|
|
117
|
+
return
|
|
118
|
+
ctx.spans.append(
|
|
119
|
+
CustomSpan(
|
|
120
|
+
name=name,
|
|
121
|
+
kind="event",
|
|
122
|
+
offset_ms=ctx.elapsed_ms(),
|
|
123
|
+
duration_ms=0.0,
|
|
124
|
+
metadata=dict(metadata) if metadata else {},
|
|
125
|
+
)
|
|
126
|
+
)
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
"""Structured exception capture with source context and redacted local variables."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import hashlib
|
|
6
|
+
import linecache
|
|
7
|
+
import os
|
|
8
|
+
import traceback
|
|
9
|
+
from typing import TYPE_CHECKING
|
|
10
|
+
|
|
11
|
+
from flask_lens.models import ExceptionFrame, ExceptionInfo
|
|
12
|
+
from flask_lens.redaction import redact_locals
|
|
13
|
+
from flask_lens.sql.listener import _is_user_frame, _shorten_path
|
|
14
|
+
|
|
15
|
+
if TYPE_CHECKING:
|
|
16
|
+
from flask_lens.config import LensConfig
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def capture_exception(exc: BaseException, config: LensConfig) -> ExceptionInfo:
|
|
20
|
+
"""Convert an unhandled exception into a structured, secret-redacted :class:`ExceptionInfo`."""
|
|
21
|
+
exc_type = f"{type(exc).__module__}.{type(exc).__qualname__}"
|
|
22
|
+
if exc_type.startswith("builtins."):
|
|
23
|
+
exc_type = type(exc).__qualname__
|
|
24
|
+
message = str(exc)
|
|
25
|
+
tb_text = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
|
|
26
|
+
|
|
27
|
+
norm_root = os.path.abspath(config.app_root) if config.app_root else None
|
|
28
|
+
frames: list[ExceptionFrame] = []
|
|
29
|
+
tb = exc.__traceback__
|
|
30
|
+
while tb is not None:
|
|
31
|
+
frame = tb.tb_frame
|
|
32
|
+
lineno = tb.tb_lineno
|
|
33
|
+
filename = frame.f_code.co_filename
|
|
34
|
+
func_name = frame.f_code.co_name
|
|
35
|
+
|
|
36
|
+
is_user = _is_user_frame(filename, norm_root)
|
|
37
|
+
display_path = _shorten_path(filename, norm_root)
|
|
38
|
+
code_line = linecache.getline(filename, lineno).rstrip()
|
|
39
|
+
|
|
40
|
+
context_lines: list[tuple[int, str]] = []
|
|
41
|
+
start_ln = max(1, lineno - 4)
|
|
42
|
+
for ln in range(start_ln, lineno + 5):
|
|
43
|
+
text = linecache.getline(filename, ln)
|
|
44
|
+
if text:
|
|
45
|
+
context_lines.append((ln, text.rstrip("\n")))
|
|
46
|
+
|
|
47
|
+
locals_preview = redact_locals(
|
|
48
|
+
frame.f_locals,
|
|
49
|
+
config.sensitive_fields,
|
|
50
|
+
enabled=config.redact_sensitive,
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
frames.append(
|
|
54
|
+
ExceptionFrame(
|
|
55
|
+
filename=display_path,
|
|
56
|
+
lineno=lineno,
|
|
57
|
+
function=func_name,
|
|
58
|
+
code_line=code_line.strip(),
|
|
59
|
+
context_lines=context_lines,
|
|
60
|
+
locals_preview=locals_preview,
|
|
61
|
+
is_user_code=is_user,
|
|
62
|
+
)
|
|
63
|
+
)
|
|
64
|
+
tb = tb.tb_next
|
|
65
|
+
|
|
66
|
+
# Group recurring exceptions by (type + deepest user frame, or deepest frame overall)
|
|
67
|
+
anchor = next((f for f in reversed(frames) if f.is_user_code), frames[-1] if frames else None)
|
|
68
|
+
fp_source = (
|
|
69
|
+
f"{exc_type}:{anchor.filename}:{anchor.lineno}:{anchor.function}" if anchor else exc_type
|
|
70
|
+
)
|
|
71
|
+
fingerprint = hashlib.sha1(fp_source.encode("utf-8")).hexdigest()[:16]
|
|
72
|
+
|
|
73
|
+
return ExceptionInfo(
|
|
74
|
+
exc_type=exc_type,
|
|
75
|
+
message=message,
|
|
76
|
+
traceback_text=tb_text,
|
|
77
|
+
frames=frames,
|
|
78
|
+
fingerprint=fingerprint,
|
|
79
|
+
)
|