{"id":7888,"library":"zprofile","title":"zprofile: Statistical CPU and Wall-Clock Profilers for Python","description":"zprofile provides statistical (sampling) CPU and wall-clock profilers for Python applications. Derived from the `google-cloud-profiler`, it allows users to collect profiling data with minimal overhead, making it suitable for production environments. The library outputs data in the `pprof` format, which can then be visualized using the external `go tool pprof`. The current version is 1.0.13, last released in August 2023, indicating a maintenance-oriented release cadence.","status":"maintenance","version":"1.0.13","language":"en","source_language":"en","source_url":"https://github.com/timpalpant/zprofile","tags":["profiling","cpu","wall-clock","performance","pprof","diagnostics"],"install":[{"cmd":"pip install zprofile","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"CPUProfiler","correct":"from zprofile.cpu_profiler import CPUProfiler"},{"symbol":"WallProfiler","correct":"from zprofile.wall_profiler import WallProfiler"}],"quickstart":{"code":"import time\nfrom zprofile.cpu_profiler import CPUProfiler\n\ndef busy_wait(duration):\n    end_time = time.time() + duration\n    while time.time() < end_time:\n        pass\n\ndef main_function():\n    print(\"Starting CPU intensive task...\")\n    busy_wait(2) # Simulate CPU work\n    print(\"CPU task complete.\")\n\np = CPUProfiler()\nprofile_data = p.profile(10) # Profile for 10 seconds\n\nwith open(\"profile.pprof\", \"wb\") as f:\n    f.write(profile_data)\n\nprint(\"CPU profile data written to profile.pprof\")\nprint(\"Use 'go tool pprof -http=:8080 profile.pprof' to view the profile.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The `go tool pprof` utility, required for viewing `zprofile`'s output, is not installed or not accessible in your system's PATH.","error":"go tool pprof: command not found"},{"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`.","cause":"The profile data was not successfully written to `profile.pprof` or the path specified to `go tool pprof` is incorrect.","error":"Error reading profile: profile.pprof: no such file or directory"},{"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`).","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.","error":"No samples found in profile."}]}