zprofile: Statistical CPU and Wall-Clock Profilers for Python

Common errors

• go tool pprof: command not found

  cause The `go tool pprof` utility, required for viewing `zprofile`'s output, is not installed or not accessible in your system's PATH.
  fix Install the Go SDK from the official Go website (golang.org/doc/install). After installation, ensure the Go bin directory (e.g., `/usr/local/go/bin`) is added to your system's PATH environment variable. Restart your terminal session.

• Error reading profile: profile.pprof: no such file or directory

  cause The profile data was not successfully written to `profile.pprof` or the path specified to `go tool pprof` is incorrect.
  fix Verify that the `p.profile()` call completed and that the `with open("profile.pprof", "wb") as f: f.write(profile_data)` block executed without errors. Check the current working directory for the `profile.pprof` file or provide the full path to `go tool pprof`.

• No samples found in profile.

  cause The profiled code either ran for too short a duration, or it did not perform significant CPU/wall-clock intensive operations during the sampling period to generate meaningful data.
  fix Increase the profiling duration (e.g., `p.profile(30)` for 30 seconds) to allow more samples to be collected. Ensure that the code being profiled is actually performing operations that `zprofile` can measure (e.g., CPU-bound tasks for `CPUProfiler`, any active time for `WallProfiler`).

Warnings

• gotcha To visualize the `.pprof` output files, you must install the Go programming language SDK and use its `go tool pprof` utility. This tool is not bundled with the `zprofile` Python library.
  Fix: Install the Go SDK from golang.org/doc/install and ensure `go tool pprof` is in your system's PATH. Then run `go tool pprof -http=:8080 profile.pprof` in your terminal to view the interactive flame graph.
• gotcha As a statistical (sampling) profiler, `zprofile` captures CPU and wall-clock usage by periodically taking samples. This approach minimizes overhead but might occasionally miss very short-lived function calls or specific line-by-line execution details that a deterministic profiler would catch. For very fine-grained analysis of short functions, consider deterministic profiling tools if overhead is acceptable.
  Fix: For general system profiling, `zprofile` is effective. If precise, per-line execution counts for extremely fast operations are needed, consider `cProfile` (built-in Python) or other deterministic profilers, understanding their potentially higher overhead. Ensure your profiled code runs long enough to generate meaningful samples (e.g., at least a few seconds).

Install

• pip install zprofile Install with pip

Imports

• CPUProfiler

  from zprofile.cpu_profiler import CPUProfiler

• WallProfiler

  from zprofile.wall_profiler import WallProfiler

Quickstart

This quickstart demonstrates how to use the `CPUProfiler` to collect CPU usage statistics over a 10-second period for a simulated busy-wait function. The collected profile data is saved to a file named `profile.pprof`, which can then be visualized using the `go tool pprof` utility.

import time
from zprofile.cpu_profiler import CPUProfiler

def busy_wait(duration):
    end_time = time.time() + duration
    while time.time() < end_time:
        pass

def main_function():
    print("Starting CPU intensive task...")
    busy_wait(2) # Simulate CPU work
    print("CPU task complete.")

p = CPUProfiler()
profile_data = p.profile(10) # Profile for 10 seconds

with open("profile.pprof", "wb") as f:
    f.write(profile_data)

print("CPU profile data written to profile.pprof")
print("Use 'go tool pprof -http=:8080 profile.pprof' to view the profile.")