https://github.com/roma-glushko/hawk
🦅 A debugging & profiling toolkit for production Python microservices
https://github.com/roma-glushko/hawk
debug fastapi flask microservices observability opentelemetry profiling python starlette tracemalloc
Last synced: 4 months ago
JSON representation
🦅 A debugging & profiling toolkit for production Python microservices
- Host: GitHub
- URL: https://github.com/roma-glushko/hawk
- Owner: roma-glushko
- License: apache-2.0
- Created: 2024-07-26T16:12:26.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-01-10T23:29:32.000Z (5 months ago)
- Last Synced: 2026-01-11T07:11:02.781Z (5 months ago)
- Topics: debug, fastapi, flask, microservices, observability, opentelemetry, profiling, python, starlette, tracemalloc
- Language: Python
- Homepage:
- Size: 2.13 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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
```bash
pip install hawk-debug
```
Optional dependencies for CPU profiling:
```bash
pip install hawk-debug[pyinstrument] # async-aware sampling profiler
pip install hawk-debug[yappi] # multi-threaded CPU/wall time profiler
```
> [!NOTE]
> This project is under development at this moment.
## Quick Start
### FastAPI
```python
from fastapi import FastAPI
from hawk.contrib.fastapi import get_router
app = FastAPI()
app.include_router(get_router())
```
### Starlette
```python
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
```python
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
| Endpoint | Description |
|----------|-------------|
| `/debug/prof/cpu/cprofile/` | CPU profile with cProfile (fixed duration) |
| `/debug/prof/cpu/cprofile/start/` | Start cProfile CPU profiling |
| `/debug/prof/cpu/cprofile/stop/` | Stop and get cProfile CPU profile |
| `/debug/prof/cpu/pyinstrument/` | CPU profile with pyinstrument (fixed duration) |
| `/debug/prof/cpu/pyinstrument/start/` | Start pyinstrument CPU profiling |
| `/debug/prof/cpu/pyinstrument/stop/` | Stop and get pyinstrument CPU profile |
| `/debug/prof/cpu/yappi/` | CPU profile with yappi (fixed duration) |
| `/debug/prof/cpu/yappi/start/` | Start yappi CPU profiling |
| `/debug/prof/cpu/yappi/stop/` | Stop and get yappi CPU profile |
| `/debug/prof/mem/tracemalloc/` | Memory profile (fixed duration) |
| `/debug/prof/mem/tracemalloc/start/` | Start memory profiling |
| `/debug/prof/mem/tracemalloc/snapshot/` | Take memory snapshot |
| `/debug/prof/mem/tracemalloc/stop/` | Stop memory profiling |
| `/debug/vars/` | Debug variables |
| `/debug/` | ZPages dashboard |
## 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.