Sampling vs deterministic profilers: which should I use?
A deterministic profiler records function-call and return events, producing call counts and timings for those calls. A sampling profiler estimates where a program spends time by observing its call stack at intervals.
Start with sampling to locate expensive work. Use deterministic profiling when the question requires exact call counts. For a choice between named tools, see Which Python profiler should I use?.
Count calls with deterministic profiling
Deterministic profilers (also called tracing or instrumenting profilers) record function entry and exit events. The standard library’s cProfile reports call counts, time spent inside each function, and cumulative time including callees. Python 3.15 also exposes it as profiling.tracing.
If a profile records 12,847 calls to parse_row in the profiled execution, that count is not an estimate inferred from samples. Call counts reveal unexpected recursion, repeated work, or a cache that never warms up.
Timing is more complicated. Recording each call adds work, and functions called frequently pay that cost more often. The program’s runtime and the distribution of costs can differ from an unprofiled run, so exact call counts do not imply undistorted timings.
Estimate time with sampling
A sampling profiler collects stack observations at intervals rather than timing every function call. A function’s share of samples estimates how often it appeared on the observed stack. A wide caller may include work performed by its callees; distinguish that inclusive cost from time spent in the function itself.
Tools like py-spy, Pyinstrument, Scalene, and Austin use sampling. Python 3.15 and later include profiling.sampling in the standard library. py-spy, Austin, and profiling.sampling run in a separate process, reading interpreter state through OS process-inspection interfaces; Scalene and Pyinstrument collect measurements inside the program.
The meaning of a sample depends on the profiler’s mode. Wall-clock profiles include waiting; CPU-oriented profiles focus on executing work. An event-loop thread’s ordinary stack samples do not, by themselves, explain which coroutine is waiting for which other task.
Sampling avoids recording every call, but its cost depends on sample rate, stack depth, enabled measurements, and workload. Attachment, permissions, and overhead are properties of the selected tool and mode.
A sampling profiler cannot tell you how many times parse_row was called. It can tell you that the program was inside parse_row for 34% of its samples. For very short functions that the sampler might never catch mid-execution, attribution gets noisy until you collect more samples.
Match the method to the question
A sampling profiler is a useful starting point for finding expensive work:
- External samplers such as py-spy attach to running programs without a restart.
- Sampling avoids the per-call instrumentation cost of deterministic profiling.
- Tools produce aggregate flame graphs, call trees, timelines, or line-level reports.
- Tools with subprocess tracking collect work across a process tree.
A deterministic profiler earns its overhead when the questions are different:
- “How many times does this function get called?” Sampling cannot answer this;
cProfilecan. - “Inside a single, short, reproducible benchmark, which of these two implementations has fewer calls to
hash()?”cProfilecounts those calls; sampling cannot recover call counts, even from a longer recording. - “Which lines in this selected function are expensive?”
line_profilerinstruments those lines to measure their cost.
Sampling also supports line-level reports. Scalene reports individual lines, and profiling.sampling produces line-level heatmaps. These reports remain statistical estimates rather than a record of every line execution.
For comparing small isolated operations, use timeit or pyperf. Profile first to choose what to investigate, then check the improvement with an unprofiled measurement and comparable inputs.
Read flame graphs as aggregates
A flame graph aggregates call stacks. Each bar represents a function, stacked vertically over its caller; its width represents its share of the sampled stacks. The horizontal axis is not elapsed time.
Two bars side by side do not establish that one ran before the other. A timeline or flame chart preserves execution order; a flame graph combines matching stacks regardless of when they appeared. Task-aware profiles or request traces help connect that work to a particular slow request.
Start with sampling and refine the investigation
On Python 3.15 and later, start with profiling.sampling; on older Python versions, py-spy provides external sampling. Check interpreter compatibility and process permissions before recording. Choose CPU or wall-clock mode based on whether waiting belongs in the result.
Use cProfile for call counts or line_profiler to instrument a selected hot function. Reach for a memory profiler like Memray when the problem is allocations or leaks rather than CPU time.