Interactive Tutorial: See Inside Your FastAPI Application¶
Welcome to sharpit. In under five minutes, this interactive walkthrough demonstrates what sharpit is, the hidden runtime problems it detects, and how both developers and AI coding agents inspect running FastAPI services.
The Problem: Passing Tests, Broken Runtime
Automated unit tests check return values and status codes, but they rarely reveal how an endpoint actually executes in production.
test_orders.py::test_get_orders PASSED [100%]
1 passed in 0.08s
Status: 200 OK
Body: {"orders": 30, "status": "active"}
The endpoint returns HTTP 200, the JSON payload matches schema, and all assertions pass.
Endpoint: GET /orders
Queries executed: 31 (1 parent + 30 repeated SELECTs)
Exceptions: 1 swallowed behind try/except (200 OK)
Configuration: insecure default fallback
A classic N+1 query pattern issues 31 queries for one page. An exception is swallowed silently, and you only discover the bottleneck in production.
One Line: Developer Console In Your App
Install sharpit and mount it to your existing FastAPI application. It activates only in development, stays on localhost, and masks secrets automatically.
pip install "sharpit[fastapi]"
from fastapi import FastAPI
import sharpit
app = FastAPI()
# Mount sharpit after your application middleware:
sharpit.install(app) # mounts /sharpit and /sharpit/api
Turns on when an enabled profile is active (dev, local, development), dev server signals are present (fastapi dev, uvicorn --reload), or SHARPIT_ENABLED=ON. A disabled profile (prod, production) or SHARPIT_ENABLED=OFF switches it off. Otherwise inactive answers 404.
Restricted to loopback callers. Reverse-proxy forwarding headers never grant trust, and remote access requires an explicit token.
Passwords, tokens, credentials, and sensitive SQL parameters are masked before filtering, display, or JSON serialization.
Inspecting panels, routes, configuration, or traces never opens a socket, writes a file, or modifies logger levels.
The Console: Correlated SQL Trace & Runtime Insights
Open http://127.0.0.1:8000/sharpit/ in your browser. Sharpit correlates every incoming HTTP request with its executed SQL statements in SQL Trace and evaluates runtime insight rules.
| Time | Statement | Duration | Rows | Call site |
|---|---|---|---|---|
| 10:14:02.120 | SELECT id, customer_id, total FROM orders WHERE status = ? | 2.0 ms | 30 | app/routes/orders.py:40 |
| 10:14:02.125 | SELECT id, order_id, product_name, price FROM order_items WHERE order_id = ? (repeated ×30) | 1.0 ms | 1 | app/routes/orders.py:42 |
sharpit insights list
$ sharpit insights list
available: true
unavailableReason: -
query: all
requests: 3
coverage: []
checksNotRun: []
observations (1)
-
id: repeated-selects:999b67bc1d
kind: repeated-selects
status: OBSERVED
subject: GET /orders
sentence: `GET /orders` ran `SELECT id, order_id, product_name, price FROM order_items WHERE order_id = ?` 5 or more times after another statement in 3 of 3 requests, up to 30 times in one.
eligible: 3
affected: 3
tier: REQUEST_ID
exemplarRequestId: req_1
verify: Open an exemplar request in Live Activity and check whether each repeat loads the children of one row the first statement returned.
listed: true
next (2)
-
command: sharpit insights show repeated-selects:999b67bc1d
tool: get_runtime_insight
arguments
id: repeated-selects:999b67bc1d
why: the evidence rows behind this repeated-selects observation, call sites included
-
command: sharpit request-profile req_1
tool: get_request_profile
arguments
id: req_1
why: one request or execution that shows it, step by step
The engine's repeated-selects analyzer evaluates query shapes across requests without slowing your database. Inspect details with sharpit insights show repeated-selects:999b67bc1d.
Checks You Can Run: Built-In Advisors
Sharpit provides automated advisor scans. Active scans run with commands like sharpit security scan or sharpit db scan (or the panel's scan button in the console); sharpit db report returns the last cached report (or NOT_SCANNED before a scan).
sharpit security scan --fail-on high
Actively reviews application security configuration, middleware filter chains, and security headers against heuristic rules to detect missing host validation, weak tokens, or disabled guards.
sharpit db scan
Introspects physical database schemas through SQLAlchemy to flag missing primary keys, unindexed foreign keys, and connection pool bottlenecks.
sharpit vulnerabilities scan
Scans installed Python packages against the OSV.dev vulnerability database to identify known CVEs affecting runtime dependencies.
sharpit architecture scan
Analyzes application classes and packages against project-agnostic structure rules to prevent layer leaks and cyclic dependencies.
In CI: Gating Builds on Runtime Evidence
Automate security checks and runtime regression gates in continuous integration pipelines using predictable exit codes.
sharpit security scan --fail-on high
Scans the running service and returns an exit code based on the highest finding severity.
pytest --sharpit
Tracks queries and swallowed exceptions per test, gates N+1 queries (sharpit.n-plus-one), and assesses REST API conventions.
CLI Exit Codes (sharpit --fail-on)
| Code | Outcome | Meaning |
|---|---|---|
0 |
SUCCESS | Scan or check completed cleanly; no findings met or exceeded the failure threshold. |
1 |
ERROR | Request error (400 invalid usage, 401 unauthenticated, 404 unknown tool, 409/429 busy, 504 timeout, 500 server error) or an evidence gate that cannot be evaluated (unscanned report, missing scan status, or no usable evidence). |
2 |
REFUSED | Action refused by policy (403 forbidden / panel disabled via configuration or read-only policy) or endpoint disabled (503). |
3 |
THRESHOLD | One or more findings reached or exceeded the --fail-on severity threshold (e.g. HIGH), or --fail-on insufficient found insufficient/partial evidence. |
Pytest Runtime Plugin Exit Codes
| Code | Outcome | Meaning |
|---|---|---|
0 |
PASS | All tests and sharpit runtime gates passed without findings. |
1 |
FAIL | Test failure or one or more sharpit runtime gates failed (e.g. sharpit.n-plus-one, sharpit.max-queries, sharpit.exception). |
FAILURES: test_orders_route
sharpit: sharpit.n-plus-one: 30 executions of one SELECT in the call phase
================================ sharpit: fail ================================
sharpit: no application found among the modules the tests imported (conftest, test modules and installed packages are not searched); rest-api skipped (pass --sharpit-app module:attr to assess the same app on any selection; --sharpit-require-app makes a missing app an error instead of a skip)
status: fail
tests with findings: 1
gate counts:
sharpit.n-plus-one: 1
worst tests:
test_sample.py::test_orders_route: 1 finding(s)
report: sharpit-report.json
sharpit checked: test-runtime gates (sharpit.max-queries, sharpit.n-plus-one, sharpit.exception)
sharpit did not check: REST API, vulnerabilities, database-advisor, security, architecture, fastapi; routes and SQL your tests did not exercise; security testing (sharpit does no attack or penetration testing)
With an AI Agent: Runtime Grounding vs Guesswork
AI coding agents often struggle with performance bugs because static source code does not show query execution counts or runtime bottlenecks.
- The agent reads static files, greps through logs, and guesses execution frequency.
- It hypothesizes whether an ORM relationship loads lazily or eagerly.
- Proposes trial-and-error edits with no way to verify runtime query counts.
- Risk of introducing regressions or unnecessary premature optimizations.
- Agent queries the running application over MCP (
/sharpit/api/mcp) or CLI (sharpit activity --json). MCP is off by default: enable it withSHARPIT_MCP_ENABLED=ON,sharpit.install(app, mcp_enabled="ON"), the MCP Server panel switch, orsharpit mcp enable. - Follows structured diagnostic playbooks (e.g.
database-efficiency.md). - Receives masked, bounded evidence with exact statement fingerprints and call sites.
- Verifies the fix immediately: one query with an IN list, or a join.
Learn how to connect Claude Code, Cursor, Codex, or custom agents: read the full AI agents guide.
Try It: Get Started in Seconds
Add sharpit to your FastAPI project today to eliminate runtime surprises and give your team real visibility.
pip install "sharpit[fastapi]"
# or using uv:
uv add "sharpit[fastapi]"
from fastapi import FastAPI
import sharpit
app = FastAPI()
# Register application middleware first, then mount sharpit:
sharpit.install(app)
fastapi dev app.py # or: uvicorn app:app --reload
Then open http://127.0.0.1:8000/sharpit/ in your browser.