Profiling with py-spy

Overview

py-spy is a sampling profiler for Python that visualizes what your code spends time on without restarting the process.

Docker Setup

Dockerfile

RUN pip install py-spy

docker-compose.yml

services:
  app:
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp:unconfined

Usage

1. Find Process ID

docker exec -it cloud-document-maker ps aux
# Look for gunicorn worker process (not master)

2. Record Profile

# Record to SVG flamegraph
docker exec -it cloud-document-maker py-spy record \
  -o /app/output/profile.svg --pid <WORKER_PID>

# Record with duration limit (60 seconds)
docker exec -it cloud-document-maker py-spy record \
  -o /app/output/profile.svg --pid <WORKER_PID> --duration 60

# Record to speedscope format (interactive viewer)
docker exec -it cloud-document-maker py-spy record \
  -o /app/output/profile.json --format speedscope --pid <WORKER_PID>

3. Real-time Monitoring

# Live top-like view of function calls
docker exec -it cloud-document-maker py-spy top --pid <WORKER_PID>

4. View Flamegraph

Open ./output/profile.svg in browser.

Reading Flamegraphs

Element	Meaning
Width	Time spent in function
Height	Call stack depth
Wide bars	Performance hotspots
Color	Random (no meaning)

Tips:

• Look for wide bars at the top — these are slow leaf functions
• Click on bars to zoom in
• Search for specific function names

Troubleshooting

Error	Solution
Permission denied	Add SYS_PTRACE to docker-compose
Process not found	Worker may have restarted, re-check PID

Output Formats

Format	Use Case
svg	Static flamegraph (default)
speedscope	Interactive web viewer
raw	Raw sample data