Add instrumentation for memory profiling in Python SDK

[tvalentyn]

This change adds instrumentation launch Python SDK Harness with custom profiling agents and adds memory Profiling capabilities with off-the-shelf profilers.

Design: https://s.apache.org/beam-python-memory-profiling

Requires these dependencies in the runtime environment (included in Beam default containers):

• memray(https://pypi.org/project/memray/) pip package for profiling with Memray
• google-pprof apt package for profiling with tcmalloc
• gcloud cli for uploading profiles to GCS.

To enable memory profiling with Memray:

python pipeline.py  --runner=DataflowRunner   --profiler_agent=memray

By default, binary profiles are all uploaded to the <TEMP_LOCATION>/profiles and we are attempting to do basic profile postprocessing on the worker by creating memray flamegraphs.

Additional optional params:

• To use native mode (for profiling extensions) or other memray run options, pass them like so: --profiler_extra_arg="--native". For more information, see https://bloomberg.github.io/memray/run.html.
• To use aggregated mode, cap profiler duration (worker will be terminated+restarted): --profiler_extra_arg="--aggregate" --profiler_stop_after_sec=600
• To use custom location for saving profiles: --profile_location=gs://your-bucket/profiles
• To configure profile uploading and post-processing intervals: --profile_upload_interval_sec=60 --profile_postprocess_interval_sec=60

To enable memory profiling with TCMalloc:

python pipeline.py --runner=DataflowRunner --profiler_agent=tcmalloc

To supply additional envirionment variables, pass them individually with this option: --profiler_extra_env_vars="HEAP_PROFILE_TIME_INTERVAL=600". For more information, see: https://gperftools.github.io/gperftools/heapprofile.html

Other options:

• To stop after first process crash: --profiler_stop_after_crash . This might help address any instability associated with enabling a profiler.

fixes: #20298

---

Thank you for your contribution! Follow this checklist to help us incorporate your contribution quickly and easily:

• Mention the appropriate issue in your description (for example: addresses #123), if applicable. This will automatically add a link to the pull request in the issue. If you would like the issue to automatically close on merging the pull request, comment fixes #<ISSUE NUMBER> instead.
• Update CHANGES.md with noteworthy changes.
• If this contribution is large, please file an Apache Individual Contributor License Agreement.

See the Contributor Guide for more tips on how to make review process smoother.

To check the build health, please visit https://github.com/apache/beam/blob/master/.test-infra/BUILD_STATUS.md

GitHub Actions Tests Status (on master branch)

See CI.md for more information about GitHub Actions CI or the workflows README to see a list of phrases to trigger workflows.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 255 lines in your changes missing coverage. Please review.
✅ Project coverage is 57.71%. Comparing base (d9117f4) to head (d1f3b01).
⚠️ Report is 11 commits behind head on master.

Files with missing lines	Patch %	Lines
sdks/python/container/profiler.go	0.00%	199 Missing ⚠️
sdks/python/container/boot.go	0.00%	56 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #38853      +/-   ##
============================================
- Coverage     57.77%   57.71%   -0.06%     
  Complexity    12969    12969              
============================================
  Files          2509     2510       +1     
  Lines        260525   260768     +243     
  Branches      10658    10658              
============================================
- Hits         150516   150507       -9     
- Misses       104318   104570     +252     
  Partials       5691     5691              

Flag	Coverage Δ
go	28.64% <0.00%> (-0.10%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[tvalentyn]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces profiling capabilities to the Apache Beam Python SDK worker harness, adding pipeline options to configure profiling agents (like memray and tcmalloc) and implementing background tasks in the Go bootloader to manage profiling, GCS uploads, and post-processing. Feedback on these changes highlights several critical improvements: replacing a potentially failing syscall.Kill with Go's standard process signaling, resolving an ARM64 compatibility issue by avoiding hardcoded absolute paths for tcmalloc, executing memray post-processing sequentially to prevent worker OOMs, implementing a cleanup mechanism for local profile files to avoid disk exhaustion, and fixing a goroutine/ticker leak by handling context cancellation.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[tvalentyn]

R: @jrmccluskey

[github-actions]

Stopping reviewer notifications for this pull request: review requested by someone other than the bot, ceding control. If you'd like to restart, comment assign set of reviewers