Skip to content

Flowsurgeon

Flowsurgeon is an application instrumentation tool and query tracker designed for Python web applications. It serves as a developer dashboard, intercepting incoming web requests (both WSGI and ASGI) and database interactions (SQLAlchemy, DB-API) to provide real-time profiling, SQL query tracing, and call-stack visualization.

Here is the story of Flowsurgeon's development, following the git commit history and its architectural phases.

timeline
    title Flowsurgeon Evolution
    v0.1.0 - v0.2.0 : Core Instrumentation : WSGI/ASGI middleware to capture request context
    v0.3.0 - v0.5.0 : Database & Profiling : SQLAlchemy hooks, DB-API query tracking, and line profiling
    Phase 1 - Phase 2 : Dashboard UI & Routing : CSS design systems, Swagger-style routes list, prefix grouping
    Phase 3 - v0.6.0 : Interactive SPA Polish : Alpine.js toggle groups, Light/Dark modes, Playwright test captures

Phase 1: Context Capture & Middleware (Commits 047b799 - 340ad0b)

The project started with a modern python configuration structure following PEP 621. Its goal was to intercept incoming network traffic:

  • WSGI Interceptor: A middleware layer designed to capture request metrics (path, method, duration) in traditional frameworks like Flask.
  • ASGI Middleware: Extended tracing support to modern asynchronous Python frameworks (FastAPI, Starlette), allowing flow capturing inside async request pipelines.

Phase 2: Database Tracing & Call-Stack Profiling (Commits 8b51955 - 1953f82)

The tool evolved from simple route tracing to deep database and logic inspections:

  • DB-API & SQLAlchemy Hooking: Flowsurgeon wraps the PEP 249 DB-API and hooks into SQLAlchemy connection events to intercept raw SQL queries, tracking their exact execution speed, parameters, and database roundtrips.
  • Line Profiling: Integrated CPU execution profiling to let developers identify exact bottlenecks within their endpoint handler code.

Phase 3: Developer Dashboard & Design Systems (Commits 379999a - ac9dc67)

To make the captured data useful, the project introduced a local developer panel overlay:

  • Utility CSS migration: Removed inline styles and laid out a consistent CSS design system within the base panel template.
  • Visual Method Indication: Added distinctive color indicators for different HTTP verbs (e.g., green for GET, blue for POST) to make the request list scannable.

Phase 4: Route Layouts & Swagger-style UX (Commits a04a800 - a1ba3c0)

The dashboard UI was restructured to serve as a hub for inspecting applications:

  • Swagger-Style Routing Index: The landing page was updated to list all application routes, grouped automatically by path prefix.
  • Route Details: Built route-specific detail sheets showing execution logs, database queries triggered by that path, and breadcrumb navigation links.

Phase 5: SPA Polish & Alpine.js Toggle Groups (Commits 8f8c7ff - 8a7f901)

The UI was polished to feel premium, responsive, and lightweight:

  • Alpine.js SPA Integration: Replaced heavy state changes with Alpine.js, converting the page into a fast Single Page Application (SPA).
  • Layout Density: Tightened spacing density, removed heavy animations, and added a Light/Dark mode switcher.
  • Expanded Tables: Streamlined details table columns to fit query texts, full request IDs, and relative times.

Phase 6: Automation & Release v0.6.0 (Commits c187ebe - f7b97ee)

The final phase added automation and release management:

  • Playwright Visual Testing: Added Playwright scripts to automatically render and capture screenshots of the developer panel.
  • v0.6.0 Release: Packaged and published the dashboard assets alongside the Python library.