Sampling and Wall-Clock Time

Timing anything in Python starts with choosing the clock that answers the question you are actually asking, and the `time` module deliberately exposes several because they measure different things. ## Wall-clock time **Wall-clock time** is what a stopwatch on the desk measures: real elapsed time between two moments. In Python you read it with `time.perf_counter()`, which returns a float of fractional seconds from an undefined origin. Only differences are meaningful — the absolute value has no calendar meaning. Two properties make it the right default for measuring durations: * It is **monotonic**: it never goes backwards, so an NTP correction or a daylight-saving change in the middle of your measurement cannot produce a negative duration. * It has the **highest resolution** the platform offers, typically nanoseconds, which matters when the thing you are timing is short. `time.monotonic()` shares the monotonic guarantee; `perf_counter()` is the one documented as the highest-resolution choice for benchmarking. `time.perf_counter_ns()` returns the same clock as an integer number of nanoseconds and avoids float rounding, which is worth using when you accumulate many small intervals. `time.time()` is a different animal: it is the wall *date-time*, seconds since the Unix epoch, and it is not monotonic. It is the correct clock for "when did this happen" and the wrong clock for "how long did this take". ## CPU time **CPU time** is how much processor time the operating system charged to your process — user time in your code plus system time in kernel calls made on your behalf. `time.process_time()` returns it, in fractional seconds, and the documentation is explicit that time elapsed during sleep is *not* included. `time.process_time_ns()` is the integer-nanosecond variant. Because it is a sum over all threads of the process, a program that saturates four cores for one real second reports roughly four seconds of process time. That is not a bug — it is the definition. If you want the CPU consumed by one specific thread, that is `time.thread_time()`. ## Where the two diverge The interesting number is the *gap*: ```python import time wall = time.perf_counter() cpu = time.process_time() time.sleep(0.25) # waiting: wall grows, CPU does not sum(range(2_000_000)) # computing: both grow print(time.perf_counter() - wall, time.process_time() - cpu) ``` Wall time that greatly exceeds CPU time means the process spent its life *waiting*. The usual causes are network or disk I/O, a `time.sleep()` in a retry backoff, blocking on a lock or a queue, waiting on a child process, or simply being starved of CPU on a loaded machine. CPU time close to wall time means the process was genuinely computing, and profiling Python code is then the productive next step. The reverse — CPU time much larger than wall time — means real parallelism: several threads running C code that released the GIL, or a free-threaded build (officially supported since Python 3.14) running Python bytecode on several cores at once. ## Why this is the first thing to measure This distinction is what makes a CPU-oriented call profile misleading on an I/O-bound job. A deterministic profiler records function calls and returns; if your program is blocked inside one call for thirty seconds, the profiler faithfully reports one call, and nothing looks "hot". Knowing that wall time is thirty seconds while CPU time is one second tells you immediately that the answer is not in the function-call report at all, and sends you to wall-clock accounting instead — bracketing each phase of the job with `perf_counter()` readings, or using a sampling profiler that samples on wall-clock. ## Practical rules * Measure durations with `perf_counter()` (or `perf_counter_ns()`), never `time.time()`. * Record both wall and CPU for anything long-running; the ratio is free diagnostic information. * Subtract readings of the *same* clock; the clocks have unrelated origins. * Do not compare a wall-clock number from one machine with one from another under different load — wall time includes everybody else's work on that box. * `time.get_clock_info('perf_counter')` reports that clock's resolution and monotonicity on the current platform if you need to know what you are actually resolving. ## Which clock for which question * *How long did this take?* — `time.perf_counter()`. * *When did this happen?* — `time.time()`. * *How much processor did this cost?* — `time.process_time()`. * *How much processor did this one thread cost?* — `time.thread_time()`. Nothing here answers *where* the time went inside the program; that is what phase timers and profilers are for. But the wall-versus-CPU split decides which of those instruments can possibly help, and it is two lines of code, so it belongs at the top of every investigation into a slow Python program rather than after a wasted afternoon of reading call reports.