Hawk

Lightweight debugging & profiling toolkit
for production 🐍Python services

Features

• Memory Profiling - tracemalloc-based allocation tracking
• CPU Profiling - cProfile (built-in), pyinstrument (async-aware), yappi (multi-threaded)
• Debug Vars - expose internal service state
• ZPages - custom debug dashboard
• On-demand activation - profile only when needed, download profiles for further investigation or render them in the browser
• No elevated permissions required (like CAP_PTRACE)
• Enable/disable via environment variables without code changes

Installation

pip install hawk-debug

Optional dependencies for CPU profiling:

pip install hawk-debug[pyinstrument]  # async-aware sampling profiler
pip install hawk-debug[yappi]          # multi-threaded CPU/wall time profiler

Quick Start

FastAPI

from fastapi import FastAPI
from hawk.contrib.fastapi import get_router

app = FastAPI()
app.include_router(get_router())

Starlette

from starlette.applications import Starlette
from starlette.routing import Mount
from hawk.contrib.starlette import get_router

app = Starlette(routes=[
    Mount("/debug", app=get_router()),
])

Flask

from flask import Flask
from hawk.contrib.flask import create_debug_blueprint

app = Flask(__name__)
app.register_blueprint(create_debug_blueprint(), url_prefix="/debug")

Endpoints

Query Parameters

CPU Profiling (cProfile)

• duration - profile duration in seconds (default: 5)
• format - output: text, json, pstat (binary)
• sort - sort by: cumulative, time, calls, name
• limit - number of functions to show (default: 30)

CPU Profiling (pyinstrument)

• duration - profile duration in seconds (default: 5)
• format - output: html, json, speedscope
• interval - sampling interval (default: 0.001)
• async_mode - enabled, disabled, strict

CPU Profiling (yappi)

• duration - profile duration in seconds (default: 5)
• format - output: funcstats (JSON), pstat (binary), callgrind (for KCachegrind)
• clock_type - cpu (CPU time) or wall (wall clock time)
• builtins - profile built-in functions (default: false)
• multithreaded - profile all threads (default: true)

Memory Profiling

• duration - profile duration in seconds (default: 5)
• format - output: lineno, traceback, pickle
• frames - stack frames to capture (default: 30)
• count - top N allocations (default: 10)
• gc - run GC before profiling (default: true)

Integrations

Inspiration

Inspired by Go's net/http/pprof, expvars, and OpenTelemetry Collector's ZPages.