FastAPI Profiler

https://github.com/sunhailin-leo/fastapi_profiler
Admin
FastAPI Profiler is a FastAPI middleware powered by pyinstrument that profiles service performance,...
Tokens:24,953
Snippets:284
Trust Score:9.4
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install fastapi_profiler

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Install the package using pip or uv.

```bash
pip install fastapi_profiler -U
# or with uv:
uv add fastapi_profiler
```

--------------------------------

### Run Application

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Start the FastAPI server using uvicorn.

```bash
uvicorn main:app --host 0.0.0.0 --port 8000
```

--------------------------------

### Install project dependencies

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/README.md

Use uv to install all project dependencies including development tools.

```shell
$ uv sync --group dev
```

--------------------------------

### Install fastapi_profiler

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/README.md

Installation commands for different package managers.

```shell
$ uv add fastapi_profiler
```

```shell
$ pip install fastapi_profiler -U
```

--------------------------------

### Log Format Output Examples

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/types-and-configuration.md

Example output strings for text and JSON logging formats.

```text
Method: GET, Path: /api/users, Duration: 123.456ms, Status: 200
```

```json
{"logger": "fastapi_profiler", "method": "GET", "path": "/api/users", "duration_ms": 123.456, "status_code": 200}
```

--------------------------------

### Create a ProfileRecord instance

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/stats-api.md

Example demonstrating how to instantiate a record using the create factory method.

```python
from fastapi_profiler.stats import ProfileRecord

record = ProfileRecord.create(
    path="/api/users",
    method="GET",
    status_code=200,
    duration_ms=45.3,
    profile_output="function call tree output..."
)
print(record.request_id)  # UUID4 string
print(record.timestamp)   # ISO 8601 UTC timestamp
```

--------------------------------

### Minimal FastAPI Profiler Setup

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/README.md

Basic middleware registration for standard profiling output.

```python
from fastapi import FastAPI
from fastapi_profiler import PyInstrumentProfilerMiddleware

app = FastAPI()
app.add_middleware(PyInstrumentProfilerMiddleware)
```

--------------------------------

### Initialize and mount dashboard router

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/dashboard-api.md

Example of how the middleware internally initializes the dashboard router and mounts it to the application.

```python
# Internal use by PyInstrumentProfilerMiddleware
router = create_dashboard_router(
    stats_collector=self._stats_collector,
    get_enabled=lambda: self._enabled,
    set_enabled=self._set_enabled,
    get_config=self._get_runtime_config,
    set_config=self._apply_runtime_config,
)
app.mount("/__profiler__", router)
```

--------------------------------

### Basic Text Profiling

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/api-reference.md

Standard setup to output profile summaries to stdout.

```python
import uvicorn
from fastapi import FastAPI
from fastapi_profiler import PyInstrumentProfilerMiddleware

app = FastAPI()
app.add_middleware(PyInstrumentProfilerMiddleware)

@app.get("/api/test")
async def test_endpoint():
    return {"message": "Hello World"}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

--------------------------------

### Handle Configuration Errors

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/dashboard-api.md

Examples of invalid requests that trigger a 400 Bad Request response.

```bash
# Invalid sample_rate (out of range)
curl -X POST http://localhost:8000/__profiler__/config \
     -H "Content-Type: application/json" \
     -d '{"sample_rate": 1.5}'
# Returns 400: {"error": "sample_rate must be a number between 0.0 and 1.0"}

# Invalid JSON
curl -X POST http://localhost:8000/__profiler__/config \
     -H "Content-Type: application/json" \
     -d '{"enabled": invalid}'
# Returns 400: {"error": "invalid JSON body"}
```

--------------------------------

### Configure FastAPI Profiler Middleware

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/usage-examples.md

A production-ready setup demonstrating middleware integration with sampling, thresholding, structured logging, and dashboard enablement.

```python
import logging
import os
import uvicorn
from fastapi import FastAPI
from fastapi.responses import JSONResponse
from fastapi_profiler import PyInstrumentProfilerMiddleware

# Structured logging
logging.basicConfig(level=logging.INFO, format="%(message)s")

app = FastAPI()

app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    # Output configuration
    profiler_output_type="text",
    is_print_each_request=True,
    # Sampling & thresholds
    profiler_sample_rate=0.5,           # Profile 50% of requests
    slow_request_threshold_ms=100,      # Only emit when > 100ms
    always_profile_errors=True,         # But always profile 5xx
    # Logging
    log_format="json",                  # Structured JSON logs
    # Statistics & history
    max_profiles_per_route=10,          # Keep last 10 profiles per route
    # Dashboard
    enable_dashboard=True,
    dashboard_path="/__profiler__",
    filter_paths=["/__profiler__"],     # Exclude dashboard from profiling
    # Runtime control
    enabled=True,
)

@app.get("/api/users")
async def list_users():
    return JSONResponse({"users": [1, 2, 3]})

@app.get("/api/slow")
async def slow_operation():
    import asyncio
    await asyncio.sleep(0.15)
    return JSONResponse({"status": "done"})

@app.get("/api/error")
async def error_operation():
    return JSONResponse(
        {"error": "Internal server error"},
        status_code=500
    )

if __name__ == "__main__":
    # Start: python app.py
    # Dashboard: http://localhost:8000/__profiler__
    # Adjust at runtime: curl -X POST http://localhost:8000/__profiler__/config -d '...'
    uvicorn.run(app, host="0.0.0.0", port=8000, workers=1)
```

--------------------------------

### Verify Profiler Configuration

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/usage-examples.md

Retrieves current profiler settings using a GET request.

```bash
curl http://localhost:8000/__profiler__/stats | jq '.enabled, .sample_rate, .slow_request_threshold_ms'
```

--------------------------------

### Project Directory Structure

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/INDEX.md

The file layout of the fastapi_profiler source code and example implementations.

```text
fastapi_profiler/
├── __init__.py              # Public API exports
├── profiler.py              # PyInstrumentProfilerMiddleware (main middleware)
├── stats.py                 # StatsCollector, RouteStats, ProfileRecord
├── dashboard.py             # Dashboard router and HTML/API implementation
├── _version.py              # Version information
example/
├── fastapi_example.py                           # Basic setup
├── fastapi_to_html_example.py                   # HTML output
├── fastapi_to_json_example.py                   # JSON output
├── fastapi_to_prof_example.py                   # cProfile output
├── fastapi_to_speedscope_example.py             # Speedscope output
├── fastapi_sampling_rate_example.py             # Sampling
├── fastapi_always_profile_errors_example.py     # Error profiling
├── fastapi_json_logging_example.py              # JSON logging
├── fastapi_stats_dashboard_example.py           # Dashboard
├── fastapi_per_route_history_example.py         # Profile history
├── fastapi_runtime_toggle_example.py            # Runtime config
└── fastapi_full_features_example.py             # All features
```

--------------------------------

### GET /__profiler__/

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/README.md

Retrieves the HTML dashboard UI for viewing profiling data.

```APIDOC
## GET /__profiler__/

### Description
Retrieves the HTML dashboard UI.

### Method
GET

### Endpoint
/__profiler__/
```

--------------------------------

### Update Profiler Configuration via cURL

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/dashboard-api.md

Examples of using cURL to modify specific profiling parameters.

```bash
curl -X POST http://localhost:8000/__profiler__/config \
     -H "Content-Type: application/json" \
     -d '{"enabled": false}'
```

```bash
curl -X POST http://localhost:8000/__profiler__/config \
     -H "Content-Type: application/json" \
     -d '{"sample_rate": 0.5}'
```

```bash
curl -X POST http://localhost:8000/__profiler__/config \
     -H "Content-Type: application/json" \
     -d '{"slow_request_threshold_ms": 100}'
```

--------------------------------

### GET /__profiler__/stats

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/README.md

Retrieves JSON statistics for all tracked routes.

```APIDOC
## GET /__profiler__/stats

### Description
Retrieves JSON stats for all routes.

### Method
GET

### Endpoint
/__profiler__/stats

### Response
#### Success Response (200)
- **enabled** (boolean) - Profiling status
- **sample_rate** (float) - Current sampling rate
- **slow_request_threshold_ms** (integer) - Threshold in ms
- **routes** (array) - List of route statistics

#### Response Example
{
  "enabled": true,
  "sample_rate": 1.0,
  "slow_request_threshold_ms": 0,
  "routes": [
    {
      "path": "/test",
      "method": "GET",
      "count": 42,
      "error_count": 1,
      "avg_duration_ms": 3.14,
      "p95_duration_ms": 8.20,
      "p99_duration_ms": 12.50,
      "max_duration_ms": 15.00
    }
  ]
}
```

--------------------------------

### GET /stats

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/types-and-configuration.md

Retrieves the current profiling statistics for all tracked routes.

```APIDOC
## GET /stats

### Description
Retrieves the current profiling statistics including route performance metrics.

### Method
GET

### Endpoint
/stats

### Response
#### Success Response (200)
- **enabled** (boolean) - Profiler status
- **sample_rate** (float) - Current sample rate
- **slow_request_threshold_ms** (number) - Current threshold
- **routes** (array) - List of route statistics
```

--------------------------------

### PyInstrumentProfilerMiddleware.__init__

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/api-reference.md

Initializes the middleware to wrap an ASGI application with profiling capabilities.

```APIDOC
## PyInstrumentProfilerMiddleware.__init__

### Description
Initializes the middleware. This class is used to wrap an ASGI application to enable request profiling.

### Parameters
- **app** (ASGIApp) - Required - The ASGI application to wrap
- **server_app** (FastAPI | Starlette | None) - Optional - Pass the FastAPI/Starlette app instance to register shutdown handler and mount dashboard. Required for file-based output types.
- **profiler_interval** (float) - Optional - pyinstrument sampling interval in seconds.
- **profiler_output_type** (str) - Optional - Output format: "text", "html", "prof", "json", or "speedscope".
- **is_print_each_request** (bool) - Optional - When True, log profile summary after every request.
- **async_mode** (str) - Optional - pyinstrument async mode setting: "enabled", "disabled", "strict".
- **html_file_name** (str | None) - Optional - Output file path for HTML profiles.
- **prof_file_name** (str | None) - Optional - Output file path for prof, json, and speedscope profiles.
- **open_in_browser** (bool) - Optional - Automatically open HTML report in default browser on server shutdown.
- **filter_paths** (list[str] | None) - Optional - List of URL path prefixes to skip profiling.
- **slow_request_threshold_ms** (float) - Optional - Only emit profile output when request duration exceeds this threshold.
- **profiler_sample_rate** (float) - Optional - Fraction of requests to profile (0.0 to 1.0).
- **always_profile_errors** (bool) - Optional - When True, 5xx responses are always profiled.
- **log_format** (str) - Optional - Log format: "text" or "json".
- **max_profiles_per_route** (int) - Optional - Maximum number of profile records to keep in memory per route.
- **enable_dashboard** (bool) - Optional - Mount built-in Web UI Dashboard.
- **dashboard_path** (str) - Optional - URL prefix for the dashboard.
- **enabled** (bool) - Optional - Master switch for profiling.

### Raises
- **ValueError** - If invalid profiler_output_type, log_format, or profiler_sample_rate values are provided.
```

--------------------------------

### Initialize PyInstrumentProfilerMiddleware

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/api-reference.md

Constructor signature for the middleware class.

```python
def __init__(
    app: ASGIApp,
    *,
    server_app=None,
    profiler_interval: float = 0.0001,
    profiler_output_type: str = "text",
    is_print_each_request: bool = True,
    async_mode: str = "enabled",
    html_file_name: Optional[str] = None,
    prof_file_name: Optional[str] = None,
    open_in_browser: bool = False,
    filter_paths: Optional[List[str]] = None,
    slow_request_threshold_ms: float = 0,
    profiler_sample_rate: float = 1.0,
    always_profile_errors: bool = True,
    log_format: str = "text",
    max_profiles_per_route: int = 10,
    enable_dashboard: bool = False,
    dashboard_path: str = "/__profiler__",
    enabled: bool = True,
    **profiler_kwargs,
) -> None
```

--------------------------------

### Initialize pyinstrument Profiler

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/internals.md

Creates a new pyinstrument Profiler instance using the current configuration settings.

```python
def _make_pyinstrument_profiler(self) -> Profiler:
    async_mode = cast(
        Literal["enabled", "disabled", "strict"],
        self._async_mode,
    )
    return Profiler(
        interval=self._profiler_interval,
        async_mode=async_mode,
    )
```

--------------------------------

### Enable Web Dashboard

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Configure the middleware with server_app and enable_dashboard to access the runtime UI.

```python
from fastapi import FastAPI
from fastapi_profiler import PyInstrumentProfilerMiddleware

app = FastAPI()

app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,  # ← Required for dashboard
    enable_dashboard=True,
    filter_paths=["/__profiler__"],  # Don't profile the dashboard itself
)
```

--------------------------------

### Combined Middleware Configuration

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/README.md

Demonstrates usage of multiple features including sampling, logging, and dashboard settings.

```python
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    # Sampling & thresholds
    profiler_sample_rate=0.5,
    always_profile_errors=True,
    slow_request_threshold_ms=100,
    # Logging
    is_print_each_request=True,
    log_format="json",
    # Dashboard & stats
    enable_dashboard=True,
    dashboard_path="/__profiler__",
    max_profiles_per_route=10,
    filter_paths=["/__profiler__"],
    # Runtime toggle
    enabled=True,
)
```

--------------------------------

### Configure Profiler for Production

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/INDEX.md

Use low sample rates and path filtering to minimize performance overhead in production environments.

```python
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    profiler_sample_rate=0.05,
    slow_request_threshold_ms=500,
    always_profile_errors=True,
    filter_paths=["/health", "/metrics"],
)
```

--------------------------------

### Configure Profiler for Development

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/INDEX.md

Enable full profiling and the dashboard for detailed performance analysis during local development.

```python
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    enable_dashboard=True,
    profiler_sample_rate=1.0,
    slow_request_threshold_ms=0,
)
```

--------------------------------

### Configure Profiler Middleware in FastAPI

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/usage-examples.md

Initializes the PyInstrumentProfilerMiddleware with dashboard support enabled.

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

app = FastAPI()
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    enable_dashboard=True,
    dashboard_path="/__profiler__",
)

@app.get("/api/test")
async def test_endpoint():
    return JSONResponse({"status": "ok"})

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

--------------------------------

### Dashboard API Response and Request Schemas

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/README.md

Example JSON structures for the dashboard stats endpoint and configuration update body.

```json
{
  "enabled": true,
  "sample_rate": 1.0,
  "slow_request_threshold_ms": 0,
  "routes": [
    {
      "path": "/test",
      "method": "GET",
      "count": 42,
      "error_count": 1,
      "avg_duration_ms": 3.14,
      "p95_duration_ms": 8.20,
      "p99_duration_ms": 12.50,
      "max_duration_ms": 15.00
    }
  ]
}
```

```json
{
  "enabled": false,
  "sample_rate": 0.5,
  "slow_request_threshold_ms": 200
}
```

--------------------------------

### PyInstrumentProfilerMiddleware.__init__

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/types-and-configuration.md

Constructor for the PyInstrumentProfilerMiddleware, used to wrap a FastAPI application with profiling capabilities.

```APIDOC
## PyInstrumentProfilerMiddleware.__init__

### Description
Initializes the middleware to profile requests in a FastAPI application.

### Parameters
- **app** (ASGIApp) - Required - The ASGI application to wrap.
- **server_app** (FastAPI | None) - Optional - FastAPI/Starlette instance required for file outputs and dashboard mounting.
- **profiler_interval** (float) - Optional - Sampling interval in seconds (default: 0.0001).
- **profiler_output_type** (str) - Optional - Output format: "text", "html", "prof", "json", "speedscope" (default: "text").
- **is_print_each_request** (bool) - Optional - Log profile after each request (default: True).
- **async_mode** (str) - Optional - pyinstrument async mode: "enabled", "disabled", "strict" (default: "enabled").
- **html_file_name** (str | None) - Optional - Output path for HTML profiles (default: "./fastapi-profiler.html").
- **prof_file_name** (str | None) - Optional - Output path for prof/json/speedscope profiles (default: "./fastapi-profiler.prof").
- **open_in_browser** (bool) - Optional - Open HTML in browser on shutdown (default: False).
- **filter_paths** (list[str] | None) - Optional - Paths to skip profiling.
- **slow_request_threshold_ms** (float) - Optional - Minimum duration to emit profile (default: 0).
- **profiler_sample_rate** (float) - Optional - Fraction of requests to profile (default: 1.0).
- **always_profile_errors** (bool) - Optional - Force-profile 5xx responses (default: True).
- **log_format** (str) - Optional - Log format for request output: "text", "json" (default: "text").
- **max_profiles_per_route** (int) - Optional - Max profile records per route in memory (default: 10).
- **enable_dashboard** (bool) - Optional - Mount Web UI Dashboard (default: False).
- **dashboard_path** (str) - Optional - Dashboard mount path (default: "/__profiler__").
- **enabled** (bool) - Optional - Master enable/disable switch (default: True).
- **profiler_kwargs** (dict) - Optional - Extra kwargs for pyinstrument's output_text().
```

--------------------------------

### Import PyInstrumentProfilerMiddleware

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/INDEX.md

Import the middleware class from the fastapi_profiler package.

```python
from fastapi_profiler import PyInstrumentProfilerMiddleware
```

--------------------------------

### Upgrade to v1.5.0

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Demonstrates backward-compatible usage and enabling new v1.5.0 features like the dashboard and sampling rate.

```python
# v1.4.0 code works unchanged
app.add_middleware(PyInstrumentProfilerMiddleware)

# Opt-in to v1.5.0 features
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    enable_dashboard=True,
    profiler_sample_rate=0.5,
)
```

--------------------------------

### Migrate from manual cProfile to PyInstrumentProfilerMiddleware

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Replaces manual cProfile decorators with middleware for automated profiling.

```python
import cProfile
import pstats
from io import StringIO

def profile_request(func):
    def wrapper(*args, **kwargs):
        profiler = cProfile.Profile()
        profiler.enable()
        try:
            return func(*args, **kwargs)
        finally:
            profiler.disable()
            s = StringIO()
            ps = pstats.Stats(profiler, stream=s).print_stats()
            print(s.getvalue())
    return wrapper

@app.get("/api/test")
@profile_request
async def test_endpoint():
    return {"status": "ok"}
```

```python
from fastapi_profiler import PyInstrumentProfilerMiddleware

app = FastAPI()
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    profiler_output_type="prof",
)
```

--------------------------------

### Conditionally Initialize Middleware

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Use environment variables to toggle the profiler middleware and configure sampling rates at runtime.

```python
import os
from fastapi import FastAPI
from fastapi_profiler import PyInstrumentProfilerMiddleware

app = FastAPI()

# Only enable profiling in development or when explicitly requested
if os.getenv("ENABLE_PROFILER", "").lower() in ("true", "1", "yes"):
    app.add_middleware(
        PyInstrumentProfilerMiddleware,
        server_app=app,
        profiler_sample_rate=float(os.getenv("PROFILER_SAMPLE_RATE", "1.0")),
        enable_dashboard=os.getenv("PROFILER_DASHBOARD", "true").lower() != "false",
    )
```

--------------------------------

### Resolve File Permissions

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Ensure the server application is provided and the output file path points to a writable directory.

```python
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,  # ← Ensure this is provided
    prof_file_name="/tmp/profile.prof",  # Use writable directory
)
```

--------------------------------

### Run Application with Environment Variables

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Execute the application with specific environment variables to control profiling behavior.

```bash
ENABLE_PROFILER=true python main.py
ENABLE_PROFILER=true PROFILER_SAMPLE_RATE=0.1 python main.py
```

--------------------------------

### Sampling and Threshold Configuration

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/api-reference.md

Limit profiling overhead by using sampling rates and duration thresholds.

```python
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    profiler_sample_rate=0.1,        # Profile 10% of requests
    slow_request_threshold_ms=200,   # Only show profiles > 200ms
    always_profile_errors=True,      # But always profile 5xx errors
)
```

--------------------------------

### Handling Configuration Errors

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/usage-examples.md

Implement try-except blocks to catch invalid middleware configuration parameters and provide fallback defaults.

```python
from fastapi import FastAPI
from fastapi_profiler import PyInstrumentProfilerMiddleware

app = FastAPI()

try:
    app.add_middleware(
        PyInstrumentProfilerMiddleware,
        profiler_output_type="invalid",  # This will raise ValueError
    )
except ValueError as e:
    print(f"Configuration error: {e}")
    # Fall back to default text output
    app.add_middleware(PyInstrumentProfilerMiddleware)
```

```python
try:
    app.add_middleware(
        PyInstrumentProfilerMiddleware,
        profiler_sample_rate=1.5,  # Out of range
    )
except ValueError as e:
    print(f"Sample rate error: {e}")
    # Use default 1.0
    app.add_middleware(PyInstrumentProfilerMiddleware)
```

--------------------------------

### StatsCollector.__init__

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/stats-api.md

Initializes a new instance of the StatsCollector with a specified capacity for profile records per route.

```APIDOC
## StatsCollector.__init__(max_profiles_per_route: int = 10)

### Description
Initializes the stats collector with a rolling window limit for profile records.

### Parameters
#### Arguments
- **max_profiles_per_route** (int) - Optional - Maximum number of profile records to keep per route in a rolling window (default: 10).
```

--------------------------------

### Configure logging for FastAPI Profiler

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/types-and-configuration.md

Sets up standard Python logging to control the verbosity of the profiler output.

```python
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("fastapi_profiler")
logger.setLevel(logging.DEBUG)  # For verbose output
```

--------------------------------

### Import ProfileRecord

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/INDEX.md

Import the ProfileRecord class to represent individual request metadata.

```python
from fastapi_profiler import ProfileRecord
```

--------------------------------

### Enable PyInstrument Dashboard in FastAPI

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/dashboard-api.md

Configures the middleware to serve a profiling dashboard at a specified path while excluding the dashboard itself from profiling.

```python
import logging
import uvicorn
from fastapi import FastAPI
from fastapi.responses import JSONResponse
from fastapi_profiler import PyInstrumentProfilerMiddleware

logging.basicConfig(level=logging.INFO, format="%(message)s")

app = FastAPI()

app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    enable_dashboard=True,
    dashboard_path="/__profiler__",
    filter_paths=["/__profiler__"],  # Don't profile dashboard itself
    is_print_each_request=True,
)

@app.get("/api/slow")
async def slow_endpoint():
    import asyncio
    await asyncio.sleep(0.2)
    return {"status": "done"}

@app.get("/api/fast")
async def fast_endpoint():
    return {"status": "quick"}

if __name__ == "__main__":
    # Start server: http://localhost:8000/__profiler__
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

--------------------------------

### Runtime Configuration via CLI

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/README.md

Uses curl commands to update the profiler configuration at runtime.

```shell
# 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}'
```

--------------------------------

### Configure Dockerfile for Profiling

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Include the profiler in your Docker image and set environment variables for automated profiling.

```dockerfile
FROM python:3.11

WORKDIR /app

RUN pip install fastapi uvicorn fastapi_profiler

COPY main.py .

ENV ENABLE_PROFILER=true
ENV PROFILER_SAMPLE_RATE=0.1

EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```

--------------------------------

### Enable Profiler via Environment Variable

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/INDEX.md

Conditionally add the middleware based on an environment variable to ensure it only runs in specific environments.

```python
import os
if os.getenv("ENABLE_PROFILER", "").lower() in ("true", "1"):
    app.add_middleware(PyInstrumentProfilerMiddleware)
```

--------------------------------

### Migrate from custom request logging to PyInstrumentProfilerMiddleware

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Replaces custom timing decorators with middleware configured for JSON logging.

```python
import time
from functools import wraps

def log_request(func):
    @wraps(func)
    async def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = await func(*args, **kwargs)
        duration = (time.perf_counter() - start) * 1000
        print(f"Route: {func.__name__}, Duration: {duration:.2f}ms")
        return result
    return wrapper

@app.get("/api/test")
@log_request
async def test_endpoint():
    return {"status": "ok"}
```

```python
import logging
from fastapi_profiler import PyInstrumentProfilerMiddleware

logging.basicConfig(level=logging.INFO, format="%(message)s")

app = FastAPI()
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    log_format="json",
    is_print_each_request=True,
)
```

--------------------------------

### Add Basic Middleware

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Register the middleware early in the application lifecycle to ensure accurate profiling.

```python
from fastapi import FastAPI
from fastapi_profiler import PyInstrumentProfilerMiddleware

app = FastAPI()

# Add profiler middleware as early as possible
app.add_middleware(PyInstrumentProfilerMiddleware)

# ... rest of your app setup ...
```

--------------------------------

### Basic Console Profiling with FastAPI

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/usage-examples.md

Configures the middleware to output text-based call trees to the console for every request.

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

app = FastAPI()
app.add_middleware(PyInstrumentProfilerMiddleware)

@app.get("/api/test")
async def test_endpoint():
    return JSONResponse({"message": "Hello World"})

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

--------------------------------

### Configure Development Profiling

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Use this configuration for local debugging to capture detailed performance data for every request, including HTML report generation.

```python
from fastapi import FastAPI
from fastapi_profiler import PyInstrumentProfilerMiddleware

app = FastAPI()

app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    # Profile everything
    profiler_sample_rate=1.0,            # 100% sampling
    slow_request_threshold_ms=0,         # Always emit
    # Verbose output
    is_print_each_request=True,
    log_format="text",
    # Fine-grained profiling
    profiler_interval=0.0001,
    # Generate HTML profiles
    profiler_output_type="html",
    html_file_name="./profile.html",
)
```

--------------------------------

### Initialize StatsCollector

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/stats-api.md

Instantiate the collector with a custom rolling window size for profile records.

```python
def __init__(self, max_profiles_per_route: int = 10)
```

```python
from fastapi_profiler.stats import StatsCollector

collector = StatsCollector(max_profiles_per_route=20)
```

--------------------------------

### Configure Structured JSON Logging

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/README.md

Outputs profiling data as structured JSON logs.

```python
import logging
logging.basicConfig(level=logging.INFO, format="%(message)s")

app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    log_format="json",  # {"logger": "fastapi_profiler", "method": "GET", ...}
)
```

--------------------------------

### Enable Web UI Dashboard

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/README.md

Activates the built-in dashboard for viewing stats and managing configuration.

```python
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    enable_dashboard=True,
    dashboard_path="/__profiler__",
    filter_paths=["/__profiler__"],  # Exclude dashboard from stats
)
```

--------------------------------

### Production Configuration for FastAPI Profiler

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/README.md

Advanced configuration for production environments, including sampling rates, thresholds, and path filtering.

```python
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    profiler_sample_rate=0.05,           # Profile 5% of requests
    slow_request_threshold_ms=500,       # Only slow requests
    always_profile_errors=True,          # Always profile 5xx
    filter_paths=["/health", "/metrics"], # Skip internal routes
    enable_dashboard=True,
    log_format="json",
)
```

--------------------------------

### PyInstrument Profiling Decision Logic

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/internals.md

Logic for determining when to initiate profiling and when to emit the resulting profile data.

```python
start_profiler = should_sample or self._always_profile_errors
# Start profiler if either:
#   - sampling says yes, OR
#   - always_profile_errors is True (for later error detection)

emit_profile = profiler is not None and (
    (should_sample and exceeds_threshold) or force_profile
)
# Emit profile output if:
#   - request was sampled AND duration >= threshold, OR
#   - request is a 5xx error AND always_profile_errors=True
```

--------------------------------

### POST /__profiler__/config

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/README.md

Updates the runtime configuration for the profiler.

```APIDOC
## POST /__profiler__/config

### Description
Update runtime configuration.

### Method
POST

### Endpoint
/__profiler__/config

### Request Body
- **enabled** (boolean) - Optional - Enable or disable profiling
- **sample_rate** (float) - Optional - Set sampling rate
- **slow_request_threshold_ms** (integer) - Optional - Set slow request threshold

### Request Example
{
  "enabled": true,
  "sample_rate": 0.5,
  "slow_request_threshold_ms": 200
}
```

--------------------------------

### Run Docker Container with Volume Mount

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Mount a local directory to persist profile output files from the container.

```bash
docker run -v $(pwd)/profiles:/app/profiles \
           -p 8000:8000 \
           -e ENABLE_PROFILER=true \
           my-fastapi-app
```

--------------------------------

### Configure Profiler Warning System

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/internals.md

Triggers a UserWarning when file-based output is configured without a server_app, ensuring the shutdown handler is correctly identified.

```python
if profiler_output_type in file_based_output_types and server_app is None:
    warnings.warn(
        f"profiler_output_type={profiler_output_type!r} writes results on "
        "server shutdown, but no server_app was provided. ...",
        UserWarning,
        stacklevel=2,
    )
```

--------------------------------

### HTML File-based Profiling

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/api-reference.md

Configure the middleware to save profile reports as HTML files.

```python
app = FastAPI()
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    profiler_output_type="html",
    html_file_name="./profile.html",
    is_print_each_request=False,
)
```

--------------------------------

### Monitor with structured JSON logs

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/README.md

Configures the middleware to output profiling information in JSON format via the logging system.

```python
import logging
logging.basicConfig(level=logging.INFO, format="%(message)s")

app.add_middleware(
    PyInstrumentProfilerMiddleware,
    log_format="json",
)
```

--------------------------------

### Fix Dashboard 404 Errors

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Provide the server_app instance to the middleware to correctly mount the dashboard.

```python
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,  # ← Required for dashboard mount
    enable_dashboard=True,
)
```

--------------------------------

### Profile all requests in development

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/README.md

Configures the middleware to profile every request with no threshold for slow requests.

```python
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    profiler_sample_rate=1.0,
    slow_request_threshold_ms=0,
)
```

--------------------------------

### Define Public Module Exports

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/internals.md

Exposes core classes and version information through the package's __init__.py file.

```python
from ._version import __author__, __version__
from .profiler import PyInstrumentProfilerMiddleware
from .stats import ProfileRecord, RouteStats, StatsCollector

__all__ = [
    "__version__",
    "__author__",
    "PyInstrumentProfilerMiddleware",
    "StatsCollector",
    "ProfileRecord",
    "RouteStats",
]
```

--------------------------------

### Configure Structured JSON Logging

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/usage-examples.md

Set up the middleware to emit request logs in JSON format for compatibility with log aggregation services.

```python
import logging
from fastapi import FastAPI
from fastapi.responses import JSONResponse
from fastapi_profiler import PyInstrumentProfilerMiddleware

# Configure logging to output raw JSON
logging.basicConfig(level=logging.INFO, format="%(message)s")

app = FastAPI()
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    log_format="json",  # Emit structured JSON logs
    is_print_each_request=True,
)

@app.get("/api/test")
async def test_endpoint():
    return JSONResponse({"result": "success"})
```

```json
{"logger": "fastapi_profiler", "method": "GET", "path": "/api/test", "duration_ms": 45.123, "status_code": 200}
```

```bash
python app.py 2>&1 | jq .  # Pretty-print JSON
python app.py > app.log 2>&1  # Redirect to file
```

--------------------------------

### Deploy to Kubernetes with Profiler

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Define environment variables within a Kubernetes deployment manifest to enable profiling.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: fastapi-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: fastapi-app
  template:
    metadata:
      labels:
        app: fastapi-app
    spec:
      containers:
      - name: fastapi
        image: my-fastapi-app:latest
        ports:
        - containerPort: 8000
        env:
        - name: ENABLE_PROFILER
          value: "true"
        - name: PROFILER_SAMPLE_RATE
          value: "0.1"
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 10
          periodSeconds: 10
```

--------------------------------

### HTML File Output Profiling

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/usage-examples.md

Generates an interactive HTML flame graph file instead of console output. Requires the server_app parameter for proper shutdown handling.

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

app = FastAPI()
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,  # Required for shutdown handler
    profiler_output_type="html",
    html_file_name="./profile.html",
    is_print_each_request=False,  # Don't log to console
)

@app.get("/api/test")
async def test_endpoint():
    return JSONResponse({"message": "test"})

if __name__ == "__main__":
    # After running, open ./profile.html in a browser
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

--------------------------------

### Configure HTML File Output

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/README.md

Writes profile data to a specified HTML file for requests exceeding the threshold.

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

--------------------------------

### Define Log Format Constants

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/types-and-configuration.md

Constants for supported logging formats and the set of valid formats.

```python
LOG_FORMAT_TEXT = "text"
LOG_FORMAT_JSON = "json"

VALID_LOG_FORMATS = {LOG_FORMAT_TEXT, LOG_FORMAT_JSON}
```

--------------------------------

### Define Default File Paths

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/types-and-configuration.md

Default file paths used by PyInstrumentProfilerMiddleware when specific filenames are not provided.

```python
DEFAULT_HTML_FILENAME = "./fastapi-profiler.html"
DEFAULT_PROF_FILENAME = "./fastapi-profiler.prof"
DEFAULT_JSON_FILENAME = "./fastapi-profiler.json"
DEFAULT_SPEEDSCOPE_FILENAME = "./fastapi-profiler-speedscope.json"
```

--------------------------------

### Request and Response Schemas

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/dashboard-api.md

JSON structures for the configuration request body and the resulting response state.

```json
{
  "enabled": boolean,
  "sample_rate": number (0.0-1.0),
  "slow_request_threshold_ms": number (≥0)
}
```

```json
{
  "enabled": boolean,
  "sample_rate": number,
  "slow_request_threshold_ms": number
}
```

```json
{
  "error": "error message describing validation failure"
}
```

--------------------------------

### Define ProfileRecord.create method signature

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/stats-api.md

The factory method signature for creating a new ProfileRecord instance.

```python
@classmethod
def create(
    cls,
    path: str,
    method: str,
    status_code: int,
    duration_ms: float,
    profile_output: Optional[str] = None
) -> "ProfileRecord"
```

--------------------------------

### PyInstrumentProfilerMiddleware

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/INDEX.md

The PyInstrumentProfilerMiddleware is an ASGI middleware designed to profile HTTP requests within a FastAPI application using the pyinstrument library.

```APIDOC
## PyInstrumentProfilerMiddleware

### Description
ASGI middleware that profiles HTTP requests using pyinstrument.

### Constructor
```python
PyInstrumentProfilerMiddleware(
    app: ASGIApp,
    *,
    server_app=None,
    profiler_interval: float = 0.0001,
    profiler_output_type: str = "text",
    is_print_each_request: bool = True,
    async_mode: str = "enabled",
    html_file_name: Optional[str] = None,
    prof_file_name: Optional[str] = None,
    open_in_browser: bool = False,
    filter_paths: Optional[List[str]] = None,
    slow_request_threshold_ms: float = 0,
    profiler_sample_rate: float = 1.0,
    always_profile_errors: bool = True,
    log_format: str = "text",
    max_profiles_per_route: int = 10,
    enable_dashboard: bool = False,
    dashboard_path: str = "/__profiler__",
    enabled: bool = True,
    **profiler_kwargs,
) -> None
```

### Public Methods
- **get_profiler_result()** -> None: Flush accumulated profile to disk (called on shutdown).
- **__call__(scope, receive, send)** -> None: ASGI interface (automatically called by framework).
```

--------------------------------

### Basic Middleware Integration

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/README.md

Adds the profiler middleware to a FastAPI application with default settings.

```python
app.add_middleware(PyInstrumentProfilerMiddleware)
```

--------------------------------

### Access Dashboard via HTTP

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/dashboard-api.md

Retrieve the interactive HTML dashboard page.

```bash
curl http://localhost:8000/__profiler__/
```

--------------------------------

### Configure Production Profiling

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Use this configuration to minimize performance impact in production by sampling requests and filtering out health check endpoints.

```python
from fastapi import FastAPI
from fastapi_profiler import PyInstrumentProfilerMiddleware

app = FastAPI()

app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    # Sampling to reduce overhead
    profiler_sample_rate=0.05,           # Profile 5% of requests
    # Thresholds to focus on slow requests
    slow_request_threshold_ms=500,       # Only profile requests > 500ms
    # Force profile errors for debugging
    always_profile_errors=True,          # Always profile 5xx
    # Skip health checks and internal routes
    filter_paths=["/health", "/ready", "/metrics", "/__profiler__"],
    # Structured logging for aggregation
    log_format="json",
    # Dashboard for monitoring
    enable_dashboard=True,
    dashboard_path="/__profiler__",
)
```

--------------------------------

### Import RouteStats

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/INDEX.md

Import the RouteStats class to handle aggregated statistics for specific API routes.

```python
from fastapi_profiler import RouteStats
```

--------------------------------

### Update Profiler Configuration in JavaScript

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/dashboard-api.md

Using the Fetch API to send a POST request to the configuration endpoint.

```javascript
async function updateConfig() {
  const response = await fetch("http://localhost:8000/__profiler__/config", {
    method: "POST",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify({
      enabled: true,
      sample_rate: 0.1,
      slow_request_threshold_ms: 50
    })
  });
  
  if (response.ok) {
    const config = await response.json();
    console.log(`Profiler enabled: ${config.enabled}`);
  } else {
    const error = await response.json();
    console.error(`Config error: ${error.error}`);
  }
}

updateConfig();
```

--------------------------------

### FastAPI Profiler with Dashboard

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/README.md

Enables the built-in web UI dashboard at a specified path.

```python
from fastapi import FastAPI
from fastapi_profiler import PyInstrumentProfilerMiddleware

app = FastAPI()
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    server_app=app,
    enable_dashboard=True,
    dashboard_path="/__profiler__",
)
```

--------------------------------

### Update Profiler Configuration in Python

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/dashboard-api.md

Asynchronous request using the httpx library to update configuration settings.

```python
import httpx

async with httpx.AsyncClient() as client:
    response = await client.post(
        "http://localhost:8000/__profiler__/config",
        json={"enabled": False, "sample_rate": 0.2}
    )
    if response.status_code == 200:
        config = response.json()
        print(f"Enabled: {config['enabled']}")
        print(f"Sample Rate: {config['sample_rate']}")
    else:
        error = response.json()
        print(f"Error: {error['error']}")
```

--------------------------------

### Inspect cProfile Output

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/usage-examples.md

Use the pstats module to analyze the generated .prof file.

```bash
python -m pstats profile.prof
# (pstats) sort cumtime
# (pstats) stats 20
```

--------------------------------

### Enable Error-Only Profiling

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/usage-examples.md

Configure the middleware to skip normal requests while capturing profiles for 5xx error responses.

```python
from fastapi import FastAPI
from fastapi.responses import JSONResponse
from fastapi_profiler import PyInstrumentProfilerMiddleware

app = FastAPI()
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    profiler_sample_rate=0.0,       # Never profile normal requests
    always_profile_errors=True,     # But always profile errors
    is_print_each_request=True,
)

@app.get("/api/error")
async def error_endpoint():
    return JSONResponse({"error": "Something failed"}, status_code=500)

@app.get("/api/success")
async def success_endpoint():
    return JSONResponse({"status": "ok"}, status_code=200)
```

--------------------------------

### Resolve output file name

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/internals.md

Determines the target file path based on the configured output type.

```python
def _resolve_output_file_name(self) -> str:
    if self._output_type == OUTPUT_TYPE_HTML:
        return self._html_file_name or self.DEFAULT_HTML_FILENAME
    if self._output_type == OUTPUT_TYPE_PROF:
        return self._prof_file_name or self.DEFAULT_PROF_FILENAME
    if self._output_type == OUTPUT_TYPE_JSON:
        return self._prof_file_name or self.DEFAULT_JSON_FILENAME
    if self._output_type == OUTPUT_TYPE_SPEEDSCOPE:
        return self._prof_file_name or self.DEFAULT_SPEEDSCOPE_FILENAME
    return ""
```

--------------------------------

### Enable Async Profiling

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/integration-guide.md

Explicitly enable async mode if the profiler fails to capture asynchronous code.

```python
app.add_middleware(
    PyInstrumentProfilerMiddleware,
    async_mode="enabled",  # Explicitly enable
)
```

--------------------------------

### Initialize StatsCollector

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/types-and-configuration.md

Defines the maximum number of profile records to retain per route.

```python
StatsCollector(max_profiles_per_route: int = 10)
```

--------------------------------

### Create Dashboard Router

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/internals.md

Define the dashboard router using callback functions to decouple state management from the middleware implementation.

```python
def create_dashboard_router(
    stats_collector,
    get_enabled: Callable[[], bool],
    set_enabled: Callable[[bool], None],
    get_config: Callable[[], dict],
    set_config: Callable[[dict], None],
) -> Router
```

--------------------------------

### Record Request Metrics

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/stats-api.md

Log performance data for a specific request. This method must be awaited.

```python
async def record(
    path: str,
    method: str,
    duration_ms: float,
    status_code: int,
    profile_output: Optional[str] = None
) -> None
```

```python
collector = StatsCollector()

await collector.record(
    path="/api/users",
    method="GET",
    duration_ms=125.3,
    status_code=200,
    profile_output="[pyinstrument output...]"
)
```

```python
try:
    await collector.record(
        path="/api/error",
        method="POST",
        duration_ms=50.0,
        status_code=500
    )
except Exception as e:
    print(f"Failed to record stats: {e}")
```

--------------------------------

### Define Python version requirements

Source: https://github.com/sunhailin-leo/fastapi_profiler/blob/main/_autodocs/types-and-configuration.md

Specifies the minimum Python version required as defined in the project configuration.

```toml
requires-python = ">=3.8"
```
Tokens:
Raw