How to use the command 'py-spy' (with examples)

py-spy is a sampling profiler for Python programs. It allows you to analyze the execution time of your Python code by collecting samples of the program’s state at regular intervals. This information can be useful for identifying performance bottlenecks and optimizing your code.

Use case 1: Show a live view of the functions that take the most execution time of a running process

Code:

py-spy top --pid pid

Motivation: The motivation for using this example is to monitor the performance of a running process in real-time. By using py-spy top, you can get a live view of the functions that are taking the most execution time, allowing you to identify areas of your code that may need optimization.

Explanation:

• py-spy top tells py-spy to start monitoring the running process and display the functions with the highest execution time.
• --pid pid specifies the process ID (pid) of the process you want to monitor.

Example output:

  %       time     Self    Child  Command
--------------------------------------------------------------------------------------------------
 48.0%  4.8ms     0.9ms   3.9ms   python path/to/file.py
 22.0%  2.2ms     0.8ms   1.4ms   functools.py
 12.0%  1.2ms     0.4ms   0.8ms   my_module.py:my_function
 ...

Use case 2: Start a program and show a live view of the functions that take the most execution time

Code:

py-spy top -- python path/to/file.py

Motivation: The motivation for using this example is to start a program and simultaneously monitor the performance of the code in real-time. By running py-spy top alongside your program, you can get instant feedback on the functions that are taking the most execution time.

Explanation:

• py-spy top tells py-spy to start monitoring the running process and display the functions with the highest execution time.
• -- separates the py-spy top command from the command to start the program.
• python path/to/file.py is the command to start the program.

Example output:

  %       time     Self    Child  Command
--------------------------------------------------------------------------------------------------
 48.0%  4.8ms     0.9ms   3.9ms   python path/to/file.py
 22.0%  2.2ms     0.8ms   1.4ms   functools.py
 12.0%  1.2ms     0.4ms   0.8ms   my_module.py:my_function
 ...

Use case 3: Produce an SVG flame graph of the function call execution time

Code:

py-spy record -o path/to/profile.svg --pid pid

Motivation: The motivation for using this example is to generate an SVG flame graph that visualizes the function call execution time. The flame graph provides a high-level overview of the program’s execution, allowing you to identify the most time-consuming functions.

Explanation:

• py-spy record tells py-spy to start recording the program’s state and collect samples.
• -o path/to/profile.svg specifies the output file path where the SVG flame graph will be saved.
• --pid pid specifies the process ID (pid) of the running process to monitor.

Example output: A flame graph saved at path/to/profile.svg that visualizes the function call execution time.

Use case 4: Dump the call stack of a running process

Code:

py-spy dump --pid pid

Motivation: The motivation for using this example is to obtain the call stack of a running process. By dumping the call stack with py-spy, you can analyze the program’s execution flow and identify any issues or bottlenecks.

Explanation:

• py-spy dump tells py-spy to dump the call stack of the running process.
• --pid pid specifies the process ID (pid) of the process to dump the call stack from.

Example output:

0   /usr/lib/python3.9/threading.py:871  wait
1   /path/to/my_script.py:42  my_function ->  some_other_function
2   /path/to/my_script.py:123 main
3   /path/to/my_script.py:124 <module>

Conclusion:

In this article, we explored several use cases of the py-spy command. We learned how to monitor the performance of a running process in real-time, generate SVG flame graphs, and dump the call stack. By leveraging py-spy, you can gain insights into the execution time of your Python code and optimize its performance.