TL;DR
Tachyon is the profiling.sampling module introduced in Python 3.15 that performs high-rate statistical stack sampling to locate runtime hotspots. It can launch scripts or attach to live processes with minimal overhead, producing outputs like flame graphs, heatmaps, and binary profiles for later replay.
What happened
Python 3.15 added profiling.sampling, nicknamed Tachyon, a statistical sampling profiler that inspects a process's call stacks at regular intervals. Unlike tracing profilers that instrument code paths, Tachyon reads stacks externally so the target process runs with effectively no added instrumentation cost. It supports launching and profiling a script or module, attaching to running processes by PID, live monitoring, and writing binary captures that can be converted to flame graphs, heatmaps, or other formats via a replay command. Tachyon exposes options for sampling rate and duration, opcode-level collection, and line-by-line heatmaps. Because it estimates time from sample counts, accuracy improves with more samples; very short programs or microbenchmarks may be better served by tracing profilers or timeit. Platform-specific permissions are required for attaching to other processes on Linux, macOS, and Windows.
Why it matters
- Allows low-overhead profiling in production since sampling reads memory externally rather than instrumenting the target process.
- Provides multiple output formats (flame graphs, heatmaps, pstats, gecko) for interactive and offline analysis.
- Enables attaching to live processes without code changes or restarts, helping diagnose issues in running systems.
- Statistical estimates scale with sample count, so longer or higher-rate sessions give more reliable hotspot identification.
Key facts
- Tachyon is available as the profiling.sampling module and was added in Python 3.15.
- It uses periodic stack sampling: taking snapshots of the call stack at fixed intervals to infer where time is spent.
- Time estimates are derived from how often functions appear in samples multiplied by the sampling interval, not from direct timing.
- Higher sample counts reduce statistical error; e.g., 100,000 samples give tighter margins than 1,000 samples.
- Tachyon supports run (launch-and-profile), attach (connect to PID), live mode, and replay (convert binary captures to visualizations).
- Output options include flame graphs, heatmaps, opcode-level views, and conversion to pstats or Firefox Profiler (gecko) formats.
- Because sampling is external, the profiled process is not instrumented and continues running at full speed; the profiler consumes CPU on the machine where it runs.
- Attaching to other processes usually requires elevated permissions; platform-specific mechanisms include ptrace/process_vm_readv on Linux and task_for_pid on macOS.
What to watch next
- Permissions and platform setup: attaching remotely or to other users' processes typically requires root/admin or specific OS settings.
- Sampling limits: very short-lived functions or programs under ~1 second may not yield reliable results; consider tracing or repeated runs.
- Interpretation noise: percentage estimates vary between runs; focus on patterns and sizeable differences rather than single-digit changes.
Quick glossary
- Statistical profiling: A profiling method that infers where time is spent by periodically sampling the program's call stack rather than instrumenting every function call.
- Sampling interval: The time gap between successive stack snapshots; shorter intervals collect more samples and increase statistical accuracy.
- Flame graph: A visualization that aggregates sampled call stacks into a stacked representation showing hot paths and relative time spent.
- ptrace / process_vm_readv: Linux mechanisms used to read another process's memory or control its execution; typically require elevated privileges.
Reader FAQ
Does Tachyon add significant overhead to the profiled program?
No — because it reads stacks externally instead of instrumenting code, the target process runs with effectively negligible profiling overhead.
Can Tachyon attach to a running Python process without restarting it?
Yes. The attach command connects to a running process by PID and collects samples without requiring a restart.
Will Tachyon report exact call counts and precise timings?
No — sampling provides statistical estimates of time spent, not exact call counts or precise measurements. For exact counts, use profiling.tracing.
Are there platform-specific permission requirements to attach to other processes?
Yes. The source describes needing elevated privileges or specific OS settings on Linux, macOS, and Windows to read another process's memory.
profiling.sampling — Statistical profiler Added in version 3.15. Source code: Lib/profiling/sampling/ The profiling.sampling module, named Tachyon, provides statistical profiling of Python programs through periodic stack sampling. Tachyon can run scripts…
Sources
- Tachyon: High frequency statistical sampling profiler
- What's new in Python 3.15
- Python 3.15 alpha 2 |First Look at Profiling and UTF-8 Default
Related posts
- How Tim Berners-Lee Built the First Web Server at CERN in 1990
- Choosing Between Codex and Claude Code: How Developers Work Differently
- Why package managers repeatedly fail when they treat Git as a database