Tracebacks

The functions below collect Python stack frames into a caller-supplied array of PyUnstable_FrameInfo structs. Because they do not acquire or release the GIL or allocate heap memory, they can be called from signal handlers and are suitable for low-overhead observability tools such as sampling profilers and tracers.

int PyUnstable_CollectCallStack(PyThreadState *tstate, PyUnstable_FrameInfo *frames, int max_frames)
This is Unstable API. It may change without warning in minor releases.

Collect up to max_frames frames from tstate into the caller-supplied frames array and return the number of frames written (0..*max_frames*). Returns -1 if frames is NULL, tstate is freed, or tstate has no current Python frame.

Filenames and function names are ASCII-encoded (non-ASCII characters are backslash-escaped) and truncated to 500 characters; if truncated, the corresponding filename_truncated or name_truncated field is set to 1.

In crash scenarios such as signal handlers for SIGSEGV, where the interpreter may be in an inconsistent state, the function might produce incomplete output or it may even crash itself.

The caller does not need to hold an attached thread state, nor does tstate need to be attached.

This function does not acquire or release the GIL, modify reference counts, or allocate heap memory.

Added in version 3.15.0a8 (unreleased).

void PyUnstable_PrintCallStack(int fd, const PyUnstable_FrameInfo *frames, int n_frames, int write_header)
This is Unstable API. It may change without warning in minor releases.

Write a traceback collected by PyUnstable_CollectCallStack() to fd. The format looks like:

Stack (most recent call first):
  File "foo/bar.py", line 42 in myfunc
  File "foo/bar.py", line 99 in caller

Pass write_header as 1 to emit the Stack (most recent call first): header line, or 0 to omit it. Truncated filenames and function names are followed by ....

This function only reads the caller-supplied frames array and does not access interpreter state. It is async-signal-safe: it does not acquire or release the GIL, modify reference counts, or allocate heap memory, and its only I/O is via write().

Added in version 3.15.0a8 (unreleased).

type PyUnstable_FrameInfo
This is Unstable API. It may change without warning in minor releases.

A plain-data struct representing a single Python stack frame, suitable for use in crash-handling code. Populated by PyUnstable_CollectCallStack().

int lineno
This is Unstable API. It may change without warning in minor releases.

The line number, or -1 if unknown.

int filename_truncated
This is Unstable API. It may change without warning in minor releases.

1 if filename was truncated, 0 otherwise.

int name_truncated
This is Unstable API. It may change without warning in minor releases.

1 if name was truncated, 0 otherwise.

char filename[Py_UNSTABLE_FRAMEINFO_STRSIZE]
This is Unstable API. It may change without warning in minor releases.

The source filename, ASCII-encoded with backslashreplace and null-terminated. Empty string if unavailable.

char name[Py_UNSTABLE_FRAMEINFO_STRSIZE]
This is Unstable API. It may change without warning in minor releases.

The function name, ASCII-encoded with backslashreplace and null-terminated. Empty string if unavailable.

Added in version 3.15.0a8 (unreleased).

Py_UNSTABLE_FRAMEINFO_STRSIZE

The size in bytes of the PyUnstable_FrameInfo.filename and PyUnstable_FrameInfo.name character arrays (501): up to 500 content bytes plus a null terminator.

Added in version 3.15.0a8 (unreleased).