Support core dump analysis with pystack and gdb.

[tvalentyn]

Support analyzing core files with pystack when python SDK processes crash with segfaults.

Sample usages:

python my_pipeline.py --runner=DataflowRunner --profiler_agent=coredump --disk_size_gb=100

Stack traces from the crash diagnostics are saved into text files that are then synced to GCS. Excerpt of the analysis is published directly into logs: we attempt to find print the stacktrace for the thread that has the GIL and surface it; the complete analysis can be retrieved from GCS (--profle_location or gs://<temp_location>/profiles by default).

Arguments to pystack can be customized via the --profiler_extra_args pipeline options.
For more information, see: https://bloomberg.github.io/pystack/ and pystack --help .

Currently this will be supported with Dataflow from Beam 2.76.0 but it should be possible to extend support to other runners.

Requires either pystack, or optionally gdb be installed in the SDK container image.
Pystack might be able to provide most insight, but if that is not sufficient users can install gdb into the container image, then we also attempt to run various gdb analysis commands and save the output into a file.

To control how often core files are postprocessed and saved, use the --profile_upload_interval_sec and --profile_postprocess_interval_sec.

Core files are deleted after the analysis to save disk space. We don't dump cores on demand, but only perform a core analysis when when a crash happened.

The --profiler_stop_after_sec and --profiler_stop_after_crash options are also supported however it does not stop core files from being saved to disk, but stops the cleanup, which may be undesirable.

Sample analysis of a manufactured segfault (retrieved from GCS).

core.python.31-20260728181728.txt

core.python.31-20260728181728.gdb.txt

---

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.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[github-actions]

Assigning reviewers:

R: @claudevdm for label python.

Note: If you would like to opt out of this review, comment assign to next reviewer.

Available commands:

• stop reviewer notifications - opt out of the automated review tooling
• remind me after tests pass - tag the comment author after tests pass
• waiting on author - shift the attention set back to the author (any comment or push by the author will return the attention set to the reviewers)

The PR bot will only process comments in the main thread (not review comments).

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[claudevdm]

Should we add a deadline (30s?) that we are willing to wait for one file?

[tvalentyn]

thanks! i think its fine to wait even longer, and process the core once write finishes. unless file is perpetually being wirtten; given this codepath is opt-in and we don't expect perpetual writes (we will run out of disk space after all), i think it's fine as is.