Registry / observability / fastapi-profiler

fastapi-profiler

JSON →
library1.5.0pypypi✓ verified 87d ago

fastapi-profiler is a FastAPI Middleware that integrates pyinstrument to provide request profiling and performance analysis for FastAPI applications. It helps developers identify bottlenecks by generating detailed reports (HTML, speedscope, JSON, .prof files). As of version 1.5.0, it supports sampling, error auto-capture, and structured JSON logging. It generally follows a regular release cadence, with several minor releases a year.

pip install fastapi-profiler
INSTALL
IMPORT
SIG · FASTAPI-PROFILER
F
fastapi-profiler
observabilitypythonv1.5.0
Install
4.1s avg
Import
—
Disk
31MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v1.5.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 32.9MB
glibc
py 3.10–3.910 runs
installs and imports cleanly · install 4.1s · import 0.000s · 32MB
31MB installed
● package 31MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PyInstrumentProfilerMiddleware
✓ from fastapi_profiler import PyInstrumentProfilerMiddleware
✗ from fastapi_profiler import FastAPIProfilerMiddleware

This quickstart demonstrates how to integrate `FastAPIProfilerMiddleware` into a FastAPI application, configure basic profiling options, and simulate a slow endpoint. It highlights saving profiles to disk, printing summaries to console, and using new features like sampling and error auto-capture. Run the app with Uvicorn and access endpoints to generate profiles.

from fastapi import FastAPI from fastapi_profiler import FastAPIProfilerMiddleware import uvicorn import time # For local development, you might enable profiling via an env var (e.g., in a .env file) # PYINSTRUMENT_PROFILING_ENABLED=true app = FastAPI() app.add_middleware( FastAPIProfilerMiddleware, profiler_dir=".", # Directory to save profile reports (e.g., HTML files) is_print_enable=True, # Print summary to console profiler_sample_rate=0.1, # Profile only 10% of requests (v1.5.0+ feature) always_profile_errors=True, # Always profile 5xx errors regardless of sample rate (v1.5.0+ feature) # is_browser_enable=True, # Requires `pip install Jinja2` to view reports in browser # html_file_name="profile_report.html", # Custom HTML report filename # log_format="json", # v1.5.0+ for structured logging ) @app.get("/") async def read_root(): time.sleep(0.05) # Simulate some work return {"message": "Hello FastAPI Profiler!"} @app.get("/slow") async def read_slow(): time.sleep(0.2) # Simulate a slow operation return {"message": "This was a slow request!"} # To run this application: # 1. Save the code as `main.py` # 2. Run from your terminal: `uvicorn main:app --reload` # 3. Access in your browser: http://127.0.0.1:8000/ or http://127.0.0.1:8000/slow # Check your current directory for profile files (.html, .json, .prof) and console output.
Debug
Known issues
gotchaRunning `fastapi-profiler` with `is_print_enable=True` or `is_browser_enable=True` (especially without `profiler_sample_rate`) in high-traffic production environments can introduce significant overhead or generate too many files. The profiler itself consumes CPU and I/O resources.
fix
In production, always set `profiler_sample_rate` to a low value (e.g., 0.01-0.1) or use environment variables like `PYINSTRUMENT_PROFILING_ENABLED=false` for a no-op. Consider `always_profile_errors=True` to catch performance issues only on failing requests. For long-term monitoring, integrate with structured logging.
affects: All versions
gotchaThe browser-based HTML report viewer functionality (`is_browser_enable=True`) requires the `Jinja2` package, which is an optional dependency. If not installed, enabling this feature will lead to runtime errors or silent failures.
fix
Ensure `Jinja2` is installed explicitly if you intend to use `is_browser_enable=True` by running `pip install Jinja2` or `pip install fastapi-profiler[browser]`.
affects: All versions
gotchaThe `log_format='json'` option, introduced in v1.5.0, changes the output format of request logs. If you rely on a specific log parsing setup that expects plain text, switching to JSON might break existing log ingestion pipelines.
fix
When upgrading to v1.5.0 or later, review your logging configuration. If you prefer the old text format, explicitly set `log_format='text'`. If migrating to JSON, update your log aggregation tools to parse the new structured output.
affects: >=1.5.0
Upgrade
Version history
1.5.0latest on PyPI · released Mar 24, 2026
Audit
Dependencies
fastapirequiredCore framework for the middleware
pyinstrumentrequiredThe underlying profiling engine
Jinja2optionalRequired for the browser-based HTML profile viewer
Agent activity
27 hits · last 30 days
node
22
OpenAI (training)
2
Resources
fastapi-profiler — pip install fastapi-profiler · libregistry