Skip to content

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.

Step 1 of 7 ~4 min interactive walkthrough
Step 1

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 Suite Output PASSED
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.

Hidden Runtime Reality DEFECTS
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.

Step 2

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
Fails Closed

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.

Localhost Only

Restricted to loopback callers. Reverse-proxy forwarding headers never grant trust, and remote access requires an explicit token.

Masks Secrets

Passwords, tokens, credentials, and sensitive SQL parameters are masked before filtering, display, or JSON serialization.

No Read Side Effects

Inspecting panels, routes, configuration, or traces never opens a socket, writes a file, or modifies logger levels.

Step 3

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.

sharpit
GET /orders Status: 200 OK Duration: 45.0 ms Queries: 31 statements
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
Runtime Insights: Repeated SELECTs 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.

Step 4

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).

Security Advisor 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.

Database Advisor sharpit db scan

Introspects physical database schemas through SQLAlchemy to flag missing primary keys, unindexed foreign keys, and connection pool bottlenecks.

Vulnerabilities (OSV) sharpit vulnerabilities scan

Scans installed Python packages against the OSV.dev vulnerability database to identify known CVEs affecting runtime dependencies.

Architecture Advisor sharpit architecture scan

Analyzes application classes and packages against project-agnostic structure rules to prevent layer leaks and cyclic dependencies.

Step 5

In CI: Gating Builds on Runtime Evidence

Automate security checks and runtime regression gates in continuous integration pipelines using predictable exit codes.

1. Standalone Security Scan
sharpit security scan --fail-on high

Scans the running service and returns an exit code based on the highest finding severity.

2. Pytest Runtime Plugin
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).
pytest --sharpit output
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)
Step 6

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.

Without sharpit SPECULATIVE
  • 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.
With sharpit BOUNDED EVIDENCE
  • Agent queries the running application over MCP (/sharpit/api/mcp) or CLI (sharpit activity --json). MCP is off by default: enable it with SHARPIT_MCP_ENABLED=ON, sharpit.install(app, mcp_enabled="ON"), the MCP Server panel switch, or sharpit 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.

Step 7

Try It: Get Started in Seconds

Add sharpit to your FastAPI project today to eliminate runtime surprises and give your team real visibility.

1. Install the package:
pip install "sharpit[fastapi]" # or using uv: uv add "sharpit[fastapi]"
2. Add to your FastAPI app:
from fastapi import FastAPI import sharpit app = FastAPI() # Register application middleware first, then mount sharpit: sharpit.install(app)
3. Run with a dev server signal:
fastapi dev app.py # or: uvicorn app:app --reload

Then open http://127.0.0.1:8000/sharpit/ in your browser.

Navigate with ← and →