fastapi_profiler

You can reduce overhead in production by using profiler_sample_rate (a float between 0.0 and 1.0). You can also ensure critical failures are always captured by setting always_profile_errors=True, which forces profiling on 5xx responses even if they fall outside the sampling rate or slow-request threshold.

# Profile only 10% of requests
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    profiler_sample_rate=0.1,
)

# Profile nothing normally, but always profile 5xx errors
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    profiler_sample_rate=0.0,
    always_profile_errors=True,
)

To get started, add PyInstrumentProfilerMiddleware to your FastAPI application using app.add_middleware(). By default, it will print profile summaries to stdout for every request.

import uvicorn
from fastapi import FastAPI
from fastapi.responses import JSONResponse
from fastapi_profiler import PyInstrumentProfilerMiddleware

app = FastAPI()
app.add_middleware(PyInstrumentProfilerMiddleware)

@app.get("/test")
async def normal_request():
    return JSONResponse({"retMsg": "Hello World!"})

if __name__ == "__main__":
    uvicorn.run(app=app, host="0.0.0.0", port=8080, workers=1)

You can install fastapi_profiler using uv (recommended) or pip.

Using uv:

uv add fastapi_profiler

Using pip:

pip install fastapi_profiler -U

Enable the dashboard by setting enable_dashboard=True. The dashboard provides a UI for viewing stats and APIs for runtime control. It is recommended to add the dashboard_path to filter_paths to avoid profiling the dashboard itself.

Dashboard API Endpoints:

• GET /{dashboard_path}/: HTML dashboard UI
• GET /{dashboard_path}/stats: JSON stats for all routes
• POST /{dashboard_path}/reset: Clear all collected stats
• POST /{dashboard_path}/config: Update runtime configuration

Example Configuration:

app.add_middleware(
    PyInstrumentProfilerMiddleware,
    enable_dashboard=True,
    dashboard_path="/__profiler__",
    filter_paths=["/__profiler__"],
)

You can change the profiler's behavior (e.g., enabling/disabling it or changing the sampling rate) without restarting the server by sending a POST request to the /{dashboard_path}/config endpoint with a JSON body.

# Disable profiling
curl -X POST http://localhost:8080/__profiler__/config \
     -H "Content-Type: application/json" \
     -d '{"enabled": false}'

# Re-enable with 50% sampling
curl -X POST http://localhost:8080/__profiler__/config \
     -H "Content-Type: application/json" \
     -d '{"enabled": true, "sample_rate": 0.5}'

The middleware uses a combination of profiler_sample_rate, slow_request_threshold_ms, and always_profile_errors to decide when to generate a profile:

1. Sampling: A request is sampled if a random roll is less than profiler_sample_rate.
2. Error Capture: If always_profile_errors is True (default), any request resulting in a 5xx status code is profiled, even if it was not selected by the sampling rate.
3. Slow Requests: If a request is sampled, it will only emit the profile output if its duration exceeds slow_request_threshold_ms.

Logic Summary: A profile is emitted if:

• (The request was sampled AND it exceeds the slow threshold)
• OR (The request is an error AND always_profile_errors is True).

The middleware can mount a lightweight HTML dashboard to view request statistics and toggle profiling settings at runtime.

To enable it, set enable_dashboard=True and you must provide the server_app argument (your FastAPI/Starlette instance). The dashboard will be available at the path specified by dashboard_path (default: "/__profiler__").

Through the dashboard, you can:

• Toggle the enabled master switch.
• Adjust sample_rate.
• Adjust slow_request_threshold_ms.

app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    enable_dashboard=True,
    dashboard_path="/my-profiler-ui"
)

To save the latest call-tree profile to an HTML file, set profiler_output_type="html". Note that server_app must be passed to enable automatic file writing on shutdown. The file is overwritten by each qualifying request, so it always contains the most recent profile.

app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    profiler_output_type="html",
    is_print_each_request=False,
    html_file_name="./fastapi-profiler.html",
)

The PyInstrumentProfilerMiddleware is an ASGI middleware that profiles HTTP requests using pyinstrument (or cProfile if profiler_output_type is set to "prof"). It can be integrated into a FastAPI or Starlette application to monitor performance, capture slow requests, and automatically profile errors.

To use the built-in Web UI dashboard, you must provide the server_app argument (typically your FastAPI instance) so the middleware can register shutdown handlers and mount the dashboard router.

from fastapi import FastAPI
from fastapi_profiler import PyInstrumentProfilerMiddleware

app = FastAPI()
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,  # Required for dashboard and file-based output shutdown hooks
    enable_dashboard=True,
    profiler_output_type="html"
)

The create_dashboard_router function initializes a Starlette Router with the following endpoints:

Parameters

• stats_collector: An object with an await get_all_stats() method and an await reset() method.
• get_enabled: A Callable[[], bool] to check if profiling is active.
• set_enabled: A Callable[[bool], None] to toggle profiling.
• get_config: A Callable[[], dict] to retrieve current configuration.
• set_config: A Callable[[dict], None] to apply configuration updates.