Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add a tutorial for pystack core #181

Merged
merged 2 commits into from
Aug 6, 2024

Conversation

PistachioCannoli
Copy link
Contributor

@PistachioCannoli PistachioCannoli commented May 21, 2024

The tutorial walks users through a core dump configuration, then uses a python script to invoke a dump with stdlib SIGABRT, and then utilizes pystack to trace the error.

*Issue number of the reported bug or feature request: #53 *

Describe your changes
Wrote a tutorial page which guides users through a stack trace with pystack's core subcommand. The tutorial starts by introducing the concept, then configures the core dump settings such as size and output location. Afterwards, it uses a test script written which follows a series of asserts, if an assert is thrown, stdlib abort is called to interrupt the program, causing a core dump. Finally, the tutorial uses the core subcommand to trace the specific python stack then uses the --native flag to show the native C frames to assess the error.

Testing performed
Tested in an environment which copied the documentation structure of memray, but I reverted all memray dependencies prior to committing my changes.

@godlygeek godlygeek changed the title added a tutorial for the core subcommand. The tutorial walks users th… docs: Add a tutorial for pystack core May 21, 2024
@sarahmonod sarahmonod changed the base branch from main to tutorial May 21, 2024 15:56
@godlygeek godlygeek deleted the branch bloomberg:main July 23, 2024 23:03
@godlygeek godlygeek closed this Jul 23, 2024
@godlygeek godlygeek reopened this Jul 23, 2024
@godlygeek godlygeek changed the base branch from tutorial to main July 23, 2024 23:05
@godlygeek godlygeek force-pushed the add-core-tutorial branch 2 times, most recently from 00c0945 to 760ecf3 Compare August 1, 2024 23:57
This tutorial walks users through a core dump configuration, then uses
a python script to invoke a dump with stdlib sigabrt, and then utilizes
pystack to trace the error.

Signed-off-by: Jon Cirone <[email protected]>
@godlygeek
Copy link
Contributor

Thanks for the contribution, @PistachioCannoli! Sorry for taking so long to get around to reviewing it.

I decided that the example program that I had suggested to you was a bit too trivial to make for an entertaining tutorial, and after a bit of effort and a few conversations I managed to come up with a real way to crash the interpreter with a segfault that works on all Python versions Memray supports, and that's much more challenging to debug with PyStack than the trivial version that just calls abort() was. So, I've pushed a commit on top of yours that drops the example program we originally came up with in favor of this new one. I also renamed the files to fit into the structure established by the other tutorial PRs, and filled in a bit more information about how to control whether and how core files are written.

Thanks to all your work here, I had a great starting point.

@sarahmonod Since I modified this so heavily, I'd rather not be the one to land it. Can you take a look and ensure I haven't made any mistakes?

@godlygeek
Copy link
Contributor

(Ignore the failing DCO check; it's just mad that I edited the Signed-off-by line to use a real name instead of a pseudonym, but we have received the DCO)

@godlygeek godlygeek force-pushed the add-core-tutorial branch 4 times, most recently from bf64dd7 to 10a08cd Compare August 2, 2024 07:13
The example I originally suggested for the core dump tutorial is a bit
too trivial to make an interesting example. Instead, Pablo helped me
come up with an example of a known way to crash the interpreter where
the root cause is not so obvious, which makes a far more engaging
example for readers to dig into and try to make sense of.

Signed-off-by: Matt Wozniski <[email protected]>
Copy link
Member

@pablogsal pablogsal left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@pablogsal pablogsal merged commit e1c338b into bloomberg:main Aug 6, 2024
20 of 21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants