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 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
+ ]
@@ -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
+ )