gh-135953: Profile a module or script with sampling profiler

[lkollar]

Add -m and filename arguments to the sampling profiler to launch the specified Python program in a subprocess and start profiling it. Previously only a PID was accepted, this can now be done by passing -p PID.

• Issue: Expose internal stack introspection APIs as a statistical runtime analysis tool #135953

[bedevere-bot]

🤖 New build scheduled with the buildbot fleet by @pablogsal for commit 1bf048a 🤖

Results will be shown at:

https://buildbot.python.org/all/#/grid?branch=refs%2Fpull%2F136777%2Fmerge

If you want to schedule another build, you need to add the 🔨 test-with-buildbots label again.

[Copilot]

Pull Request Overview

This PR extends the sampling profiler to support profiling modules and scripts by launching them in subprocesses, in addition to the existing PID-based profiling. The change improves the usability of the profiler by allowing users to profile Python programs from startup rather than only attaching to existing processes.

• Adds -m and script filename arguments as mutually exclusive alternatives to the existing -p PID option
• Updates argument parsing to handle the new target modes with proper validation
• Implements subprocess management with graceful termination handling

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
Lib/profile/sample.py	Adds argument parsing for module and script modes, implements subprocess launching and management
Lib/test/test_sample_profiler.py	Updates existing CLI tests to use -p flag and adds comprehensive test coverage for new module/script functionality

Comments suppressed due to low confidence (1)

Lib/test/test_sample_profiler.py:1637

• The test uses contextlib.chdir() to change directories for module discovery, but doesn't test the case where the module is not found or the directory change fails. Consider adding a test case for module resolution errors.

 contextlib.chdir(tempdir.name), 

[Copilot]

The condition not(args.pid or args.module or args.script) is redundant since the mutually exclusive group is already marked as required=True. The argparse library will automatically enforce that one of these options is provided.

Suggested change

	ifnot(args.pidorargs.moduleorargs.script):
	parser.error(
	"You must specify either a process ID (-p), a module (-m), or a script to run."
	)
	# The mutually exclusive group already enforces that one of these arguments is required.

[Copilot]

The hardcoded timeout of 0.1 seconds is a magic number. Consider defining this as a named constant or making it configurable, as some programs may have longer startup times.

Suggested change

	exit_code=process.wait(timeout=0.1)
	exit_code=process.wait(timeout=DEFAULT_PROCESS_WAIT_TIMEOUT)

[lkollar]

Thanks @AA-Turner, I think I addressed all your comments.

[bedevere-bot]

🤖 New build scheduled with the buildbot fleet by @pablogsal for commit 0338ee1 🤖

Results will be shown at:

https://buildbot.python.org/all/#/grid?branch=refs%2Fpull%2F136777%2Fmerge

If you want to schedule another build, you need to add the 🔨 test-with-buildbots label again.

[pablogsal]

@lkollar Seems test_sample_target_module has a race since is failin on some buildbots:

AssertionError: 'slow_fibonacci' not found in 'Captured 10001 samples in 1.00 seconds Sample rate: 10000.94 samples/sec Error rate: 99.10% Profile Stats: nsamples sample% tottime (ms) cumul% cumtime (ms) filename:lineno(function) 90/90 100.0 9.000 100.0 9.000 sample.py:96(SampleProfiler.sample) 0/90 0.0 0.000 100.0 9.000 sample.py:549(sample) 0/90 0.0 0.000 100.0 9.000 sample.py:590(wait_for_process_and_sample) 0/90 0.0 0.000 100.0 9.000 sample.py:790(main) 0/90 0.0 0.000 100.0 9.000 test_sample_profiler.py:1640(TestSampleProfilerIntegration.test_sample_target_module) 0/90 0.0 0.000 100.0 9.000 case.py:613(TestCase._callTestMethod) 0/90 0.0 0.000 100.0 9.000 case.py:667(TestCase.run) Legend: nsamples: Direct/Cumulative samples (direct executing / on call stack) sample%: Percentage of total samples this function was directly executing tottime: Estimated total time spent directly in this function cumul%: Percentage of total samples when this function was on the call stack cumtime: Estimated cumulative time (including time in called functions) filename:lineno(function): Function location and name Summary of Interesting Functions: Functions with Highest Direct/Cumulative Ratio (Hot Spots): 1.000 direct/cumulative ratio, 100.0% direct samples: sample.py:(SampleProfiler.sample) Functions with Highest Call Frequency (Indirect Calls): 90 indirect calls, 100.0% total stack presence: sample.py:(sample) 90 indirect calls, 100.0% total stack presence: sample.py:(wait_for_process_and_sample) 90 indirect calls, 100.0% total stack presence: sample.py:(main) Functions with Highest Call Magnification (Cumulative/Direct): 

[pablogsal]

why is the sample.py code in the results? Also somehow we have Error rate: 99.10%????

[pablogsal]

Oh, I think this is because we are sampling before the other process calls execv so we see the forked one! We may need some sync mechanism between the process and the profilee.

[bedevere-bot]

🤖 New build scheduled with the buildbot fleet by @pablogsal for commit 3847fff 🤖

Results will be shown at:

https://buildbot.python.org/all/#/grid?branch=refs%2Fpull%2F136777%2Fmerge

If you want to schedule another build, you need to add the 🔨 test-with-buildbots label again.