Repository navigation
Profyle 0.4: Claude Code integration, zero-code tracing and open-source readiness - #9
Merged
Merged
Conversation
Folds in the in-progress local work (uv migration, Perfetto overlay, API routes split) and finishes it so traces are stored again. Trace analysis - profyle/application/analysis/digest.py rebuilds the per-thread call tree from VizTracer events and condenses a trace (66 MB of JSON in the sample) into a ~4 KB digest: critical path per thread with framework frames collapsed, top self time, the user's own code, I/O wait and repeated calls from one caller (N+1 candidates) with sample args. Also call details, source lookup from file_info and trace comparison. - toolkit.py exposes these as read-only text tools shared by both integrations. Integrations - `profyle mcp`: MCP server for Claude Code / Claude Desktop. - `profyle analyze <id>`: print the digest, e.g. to pipe into `claude -p`. - In-app chat now uses the Anthropic SDK tool runner with the same tools, replacing the LangChain/Gemini agent. That agent shipped a hardcoded API key and let the model run arbitrary SQL against the DB. - AI dependencies are optional extras: profyle[ai], profyle[mcp]. Fixes - store_trace persists traces again; drop the unfinished normalized tables whose SQL was invalid; Trace exposes id and data again. - Remove wildcard CORS from the local server (/chat spends API credits). - PROFYLE_DB selects the SQLite file (per-project databases). - Bump FastAPI floor (0.100 broke TestClient with current httpx) and adapt TemplateResponse; add django to dev deps; quote CI python version. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
Analysis happens in Claude itself (Claude Code / Desktop through `profyle mcp`), so a second chat inside the trace viewer adds nothing. Drops the agent, the POST /chat endpoint, the chat UI in the Perfetto overlay (the header label stays) and the `ai` extra. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
…skill Replay - Middlewares (FastAPI, Flask, Django) record the request behind each trace: method, path, headers, body up to 64 KB and response status. Credentials are redacted unless PROFYLE_CAPTURE_SECRETS=true. - `profyle replay` and the `replay_request` MCP tool send it again, wait for the new trace and flag status changes. Local hosts only by default; POST/PUT/PATCH/DELETE need explicit permission. - SQLite gets a `request` column, added to existing databases on start. Plugin - claude-plugin/ bundles the MCP server and the fix-slow-endpoint skill (baseline -> diagnose -> fix -> replay -> compare -> report); .claude-plugin/marketplace.json lets users install it from this repo. - The MCP `diagnose` prompt is replaced by the skill. - PROFYLE_PROJECT_DIR (set by the plugin) finds <project>/profile.db. Fixes found while testing the journey against a real uvicorn app - On Python < 3.12, sync FastAPI endpoints were invisible from the second request on: pool threads are reused and VizTracer only hooks threads created while tracing. Enable tracing inside the worker thread for the duration of the call. - Flask middleware no longer depends on the server-specific REQUEST_URI. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
Driven by the first end-to-end run of the fix-slow-endpoint journey. - Traces live in <project>/.profyle/profile.db, found from the working directory (app, CLI) or PROFYLE_PROJECT_DIR (plugin), so the app and Claude agree without PROFYLE_DB. The folder ignores itself in git. - Responses get a fingerprint (canonical body hash, plus a JSON structure hash ignoring values). Replays and compare_traces report the body as identical / same structure / DIFFERENT and flag bodies that vary between runs. ASGI and Django record it per request; Flask traces get it from the replay. - `profyle doctor` and the `doctor` MCP tool check the database, recorded requests, the old in-package database and that the app is listening; the skill runs it first and verifies the response body. - Recording the request/response now happens after the tracer stops, so Profyle's own work no longer appears in the traces it measures. - Readers create the tables on open and the trace list includes requests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
Stored digests - traces gains `digest` and `headline` columns (migrated in place). The digest is built on the reading side, never in the app's request path: the MCP server digests new traces in a background thread and every analysis stores its result, versioned so a new analysis rebuilds it. - list_traces, slowest_endpoints (on the typical trace, not the cold slowest one) and the web list show each trace's main finding; analyze_trace no longer reparses the trace (~8 ms instead of seconds). - The headline ignores recursion, which is not a repeated-call smell. Worker threads (Python < 3.12) - Measured Django under uvicorn: sync views were traced, async views never were (the sync middleware runs in a worker thread, the view on the event loop), and sync_to_async(thread_sensitive=False) code only on the first request. asgiref's async_to_sync/sync_to_async now enable tracing in the thread that runs the code, like anyio for FastAPI. - Hooked threads are paused/resumed with VizTracer's own API in the same frame. Unhooking with sys.setprofile(None) unbalanced its stack, so a second sync callable on the same pool thread in one request (e.g. two FastAPI sync dependencies) was not traced. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
CI and releases - CI workflow: ruff, tests on Python 3.10-3.13 (3.14, macOS and Windows as non-blocking experimental jobs), tests with the lowest dependency versions allowed by pyproject.toml, build + twine check + install of the wheel in a clean environment, and Claude Code plugin manifests. - Release workflow publishing to PyPI with trusted publishing when a GitHub release is published (checks the tag matches the version). - Dependabot for GitHub Actions and uv, CODEOWNERS, pre-commit (ruff). Community files - PR template, bug report and feature request issue forms. - CONTRIBUTING, SECURITY (private reporting, safe-use notes), CODE_OF_CONDUCT (Contributor Covenant 2.1), CHANGELOG. - README: badges, overview, production warning, requirements, contributing and license sections. docs/AI_ROADMAP.md (Spanish, internal notes) replaced by an English docs/ROADMAP.md. Packaging - Version 0.4.0, SPDX license metadata, updated classifiers, keywords and project URLs; ruff settings moved under [tool.ruff.lint]. - Dependency floors fixed by testing the lowest versions: declare pydantic>=2, mcp>=2.0 (the server uses the 2.x API) and flask>=3.0 (Flask 2.x with Werkzeug 3 is broken). - sdist excludes local trace data, the plugin and CI files. Fixes found by the lowest-dependency run - The FastAPI middleware duplicated the query string in trace names when raw_path includes it (Starlette 0.38 test client). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
…le feedback Integration - `profyle run <command>` traces an app without code changes. It starts the command with a sitecustomize bootstrap whose import hooks add the middleware when FastAPI/Starlette, Flask or Django load, and around any other ASGI app served by uvicorn. Explicit middlewares take precedence, and a request marker keeps nested middlewares from tracing twice. - Generic `profyle.asgi` and `profyle.wsgi` middlewares for any framework; `profyle.fastapi` and `profyle.flask` are aliases. Configuration - One configuration for every integration: environment variables, then code (middleware arguments, Django PROFYLE_* settings), then [tool.profyle] in pyproject.toml, then defaults, with the source of each value kept for `profyle doctor`. - Fixed: PROFYLE_ENABLED=false did not disable FastAPI/Flask; a disabled Django middleware returned no response; Django read MIN_DURATION (still accepted, deprecated) and ignored the environment; the WSGI middleware skipped HTTPS; importing a middleware opened the database. - Docs: min_duration is in microseconds and filters function calls. Feedback - One console line per traced request with its main finding, built by a separate process from the stored trace so requests never wait for it; the first request of a process is flagged as warm-up. `profyle run` prints a single start-up line. - The app registers itself (framework, mode, pid, configuration) and `profyle doctor` reports it. Findings name the function holding a comprehension, or its file:line on Python 3.10. - The fix-slow-endpoint skill starts the app with `profyle run`, with the user's agreement, when nothing is traced yet. Tests: examples/ holds one app per framework with an N+1 and no Profyle code; tests/integration runs them through `profyle run` (FastAPI with --reload, flask run, Django runserver and ASGI, plain ASGI). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
Open with install / ask / verified fix, using the result of a real Claude Code session, a collapsed outline of what Claude does in between, what users no longer have to do, and the no-Claude path with `profyle run`. Badges are plain HTML so they render inside the centered block. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
Tornado (#6) - profyle.tornado.instrument(app) wraps RequestHandler._execute, so prepare(), the HTTP method and finish() of sync and async handlers are traced; it records the request, the status and a fingerprint of the response body (taken before transforms such as gzip). - `profyle run` instruments every Tornado application, under Tornado's own server and under gunicorn's tornado worker. - examples/tornado plus integration cases for both servers; extra `profyle[tornado]` (tornado>=6.1, verified at the lowest versions). Concurrency - A second request traced while another one was running overwrote the process-wide VizTracer ("Overwrite tracer!"): both traces came out wrong. A request that arrives while another one is traced is now served untraced and the console says so. Worker threads (Python < 3.12) - loop.run_in_executor (used by Tornado and plain asyncio for blocking code) now enables tracing in the executor thread like anyio/asgiref. Docs: README (Tornado, one trace at a time), CHANGELOG entries for #4, #5, #6 and #8, skill, CONTRIBUTING (lowest-version runs rewrite uv.lock), roadmap. CI lints examples/. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
The MCP server instructions and the plugin description still listed only FastAPI, Flask and Django. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
- Coverage config (branch coverage, subprocesses and execv followed, data saved on SIGTERM) with fail_under = 100, and a coverage CI job on Python 3.11. - Tests for the CLI, web viewer, MCP server, console worker, autoinstrument, sitecustomize bootstrap, middleware edge cases and worker-thread bridges. - Remove dead code: unused trace models, the redundant startup hook and application/trace/create.py. - Fix `profyle run uvicorn --factory` reporting the app as "str". - README coverage badge; CONTRIBUTING documents the coverage and pragma policy. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
Pure formatting; no behavior change. The format is now checked by CI and the pre-commit hooks. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
- Trace.id is an int; Trace.duration_ms replaces "/ 1000" everywhere; NewTrace (was TraceCreate) drops the id and timestamp it never stored, and its duration now includes the last call. - TraceRepository shrinks from 17 to 12 methods, grouped by what they are for (traces, digests, runtime). Schema creation is no longer part of the interface, and the "selected trace" table is gone: the viewer remembers the trace it opened. - SQLite repository: tables created once per process (not on every insert), listing and filtering done in SQL, no shared row_factory side effect, storage errors reported on the console, connections of the viewer closed. - RequestTrace (was the lowercase `profyle` class) matches the pattern against the request path it is given and compiles it once. - Middlewares share TRACED and the trace_repo property from base; the pass-through application/trace modules are removed. - The CLI dispatches with set_defaults; `profyle analyze` defaults to the newest trace. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
- application/analysis: call_tree.py (call tree and frame names), digest.py (a typed Digest built in one pass), drilldown.py (one function: callers, callees, source), render.py (Markdown). - application/tools replaces the 458-line toolkit.py: traces.py, replay.py, doctor.py and common.py, with the package __init__ as a table of contents. - application/requests groups request capture, response fingerprints and the request sender. - doctor is a list of small named checks; replay reports use a Run record. - Fix: get_function_source crashed when a trace pointed past the end of a file. - Tests mirror the new layout. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
Parsing a trace and writing it to SQLite used to run inside the request (blocking the event loop of async servers). Middlewares now hand it to a "profyle-store" thread: - The tracer slot is freed as soon as the tracer stops, so the next request can be traced; at most two traces wait to be stored (memory bound), and requests beyond that are served untraced. - Events of the storing threads are left out of traces (Python 3.12+ traces every thread). - Store threads are not daemons: a server shutting down keeps its last traces. - wait_until_stored() lets tests and scripts wait for pending traces; unit tests store synchronously. Extending WSGI traces over the response body was tried and dropped: test clients may never read or close the body, and ending the trace from __del__ crashes VizTracer. Documented as a known issue. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
- Both join ProfyleConfig: environment variable, code or [tool.profyle], and shown by profyle doctor with their source (replay_allow_remote is read by the tools, so doctor reports the tools' own value). - Credentials are redacted in one place, when RequestTrace resolves the recorded request, instead of inside every middleware's request capture. - check_replayable takes allow_remote explicitly instead of reading the environment. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
- WSGI traces now cover sending the response body: RequestTrace can be suspended and resumed, and the middleware traces each chunk with the tracer stopped in between. A body that is never read cannot leave the tracer running: its trace is finished by the next traced request or at exit. Flask traces now get a response fingerprint directly, so the replay workaround and TraceRepository.update_request are gone. - Fix: on Python 3.12+ the next request's tracer also recorded the background storing of the previous trace (with the repr of its huge arguments), which made that request hang. A trace now starts only once the previous one is stored; a request arriving meanwhile waits up to 5 s (async middlewares wait in a worker thread, so the event loop keeps running), and is served untraced after that. - The foreign-profiler thread test only applies before Python 3.12. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
VizTracer 1.1.1 frees a tracer's thread metadata without detaching the threads it traced; when such a thread exits later (a worker pool shutting down, interpreter exit), VizTracer writes to the freed memory and the process crashes at some later point. Confirmed with gdb on Python 3.12, where it crashed about one full test run in nine. Profyle now creates one VizTracer per configuration, reuses it for every trace (clearing its buffer first) and never frees it. threadpool records the tracers a thread is attached to in thread-local storage, since thread ids are reused. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
- VizTracer 1.1.1 clears the call stacks of every traced thread when it stops, while another thread may be recording an argument whose __repr__ runs Python code; that thread then crashes the process (reproduced deterministically on 3.10-3.13, and about once per 9 full test runs on 3.12). On Python 3.12+ Profyle now stops event delivery and gives threads a few milliseconds to finish before stopping the tracer; a regression test crashes without it. - A request that arrives while the previous trace is being suspended (between WSGI body chunks) waits for it instead of being served untraced. - console.say writes to stderr directly: VizTracer replaces print() while it traces, which swallowed messages such as "not traced". - The changelog and roadmap describe both VizTracer bugs and what remains (a __repr__ that blocks for longer can still hit the race). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
- `profyle init` writes `.mcp.json` (registering the profyle MCP server, run through `uv run`/`poetry run` when the project uses them, keeping other servers) and `.claude/skills/fix-slow-endpoint/SKILL.md`. Both can be committed, so teammates only need `pip install profyle`. Running it again updates them; an invalid `.mcp.json` is left untouched. - The skill now ships inside the package (profyle/claude/SKILL.md); the plugin keeps a copy and a test checks they match. - The MCP library is a regular dependency; the `profyle[mcp]` extra is kept, empty, so existing install commands still work. - README leads with `pip install profyle` + `profyle init`; the plugin is documented as the alternative for using Claude Code across many projects. CI smoke-tests `profyle init` from the built wheel. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
Removes the profyle entry from `.mcp.json` (deleting the file when nothing else is left in it, keeping other servers and keys otherwise), the fix-slow-endpoint skill (and `.claude` folders left empty), and the traces in `.profyle/`. Deleting traces is confirmed interactively; `--yes` skips the question and `--keep-traces` keeps them; without a terminal they are kept. It ends with the `pip uninstall profyle` step, and mentions a custom PROFYLE_DB, which it does not delete. CI smoke-tests it from the wheel. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
- "What gets traced": worker threads, streamed WSGI bodies, one request at a time, traces saved after the response. - Response fingerprints are recorded by every integration (Flask no longer needs a replay). - CLI commands as one table in workflow order (init, run, doctor, analyze, replay, start, info, clean, uninstall, mcp), replay options, a current `doctor` example, and an Uninstall section. - New Limitations section (one trace at a time, tracing overhead, unread WSGI bodies, the remaining VizTracer race). - doctor says "1 trace" instead of "1 traces". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
- "Quick start" holds only the three steps: install (pip install + profyle init), ask Claude Code, get a verified fix. - "Without Claude Code" is its own section: profyle run plus start, analyze and replay (replacing the later duplicate subsection). - "Good to know" gathers requirements, the MCP environment note, the plugin alternative and how to uninstall. - Horizontal rules separate the getting-started part from the reference. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
- build and install: check `.profyle/.gitignore` right after `profyle doctor`, before `profyle uninstall` removes it. - With VizTracer 1.0 (lowest supported), enable_thread_tracing() raises for a thread that had another profiler, where 1.1 warns; that error reached the app's call. It is now caught and the call runs untraced, with a test using a tracer that refuses, and the foreign-profiler test accepts both versions. - Coverage: test that the bootstrap runs the environment's own sitecustomize; it was only covered where Python ships one. - Python 3.14 colors argparse help under FORCE_COLOR; test_help disables it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
Owner
Author
|
This job is one of the experimental CI rows (
Supporting Windows (line-ending-safe file handling, a process check through Generated by Claude Code |
6 of 9 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Everything planned for 0.4.0. Profyle becomes a tool for Claude Code users: it traces the requests of a FastAPI / Flask / Django / Tornado (or any ASGI/WSGI) app, and Claude uses the traces to find a bottleneck, fix it and prove the fix by replaying the same request.
Setup in two commands
pip install profyle+profyle init: writes.mcp.jsonand thefix-slow-endpointskill into the project (both can be committed, so teammates only needpip install).profyle uninstallremoves everything again. The Claude Code plugin stays as an alternative.profyle[mcp]extra still works).Tracing
profyle run <command>: zero-code tracing for FastAPI/Starlette, Flask, Django (WSGI and ASGI), Tornado and any ASGI app served by uvicorn.profyle.asgi/profyle.wsgimiddlewares, Tornado support.[tool.profyle];profyle doctorshows each value and where it comes from.<project>/.profyle/(git-ignored automatically).Claude Code tools
doctor,slowest_endpoints,list_traces,analyze_trace,get_call_details,get_function_source,replay_request,compare_traces.Robustness
docs/ROADMAP.md.Code quality and open source
ruff format.Addresses #4 (PermissionError on Windows), #5 (dependency ranges too strict), #6 (Tornado support) and #8 (
profyle --helpcrash). Change these to "Fixes #N" if they should close automatically on merge.Type of change
How was it tested?
profyle runas real servers.profyle init,profyle doctorandprofyle uninstallchecked by hand and in CI.Checklist
uv run pytestpassesuv run ruff check profyle testspassesREADME.md/CHANGELOG.mdupdated if users will notice the changeclaude-plugin/skills/still describes the tools correctly🤖 Generated with Claude Code
https://claude.ai/code/session_01XW9SRqVFwcAobWhkRBmHq5
Generated by Claude Code