Welcome to stacktrace’s documentation!¶
Provide facility to obtain low-level stacktraces from within Python.
This project relies on libunwind, which works on Unix-like and OSX system.
Features¶
- Access to C stack backtrace inside Python.
- Useful for debugging code that interleave native code and Python code.
- Access to C stack of another thread in the same process.
- Useful for debugging multi-threaded programs.
Getting the dependencies¶
For development, libunwind must be available. The simplest way is to get libunwind using conda:
conda install -c defaults -c conda-forge libunwind
Install¶
Once you have the dependencies, you can run python setup.py install to install into your python package directory.
Basic API¶
These functions are for getting the C stack of a thread once.
stacktrace.print_stack([file, maxdepth, …]) |
Print the stack of the current thread. |
stacktrace.print_thread_stack(tid[, file, …]) |
Print the stack of the target thread |
stacktrace.get_thread_stack(tid[, maxdepth, …]) |
Get the stack of the target thread |
-
stacktrace.print_stack(file=None, maxdepth=100, show_python=True, _bufsize=4096)[source]¶ Print the stack of the current thread.
Parameters: - file : fileobj
The file object to print to. Defaults to
sys.stdout.- maxdepth : int
Maximum stack depth.
- show_python : bool
Whether to filter out python stack entries.
-
stacktrace.print_thread_stack(tid, file=None, maxdepth=100, show_python=True)[source]¶ Print the stack of the target thread
Parameters: - tid : int
The target thread-id.
- file : fileobj
The file object to print to. Defaults to
sys.stdout.- maxdepth : int
Maximum stack depth.
- show_python : bool
Whether to filter out python stack entries.
-
stacktrace.get_thread_stack(tid, maxdepth=100, show_python=True)[source]¶ Get the stack of the target thread
Parameters: - tid : int
The target thread-id.
- file : fileobj
The file object to print to. Defaults to
sys.stdout.- maxdepth : int
Maximum stack depth.
- show_python : bool
Whether to filter out python stack entries.
Returns: - stacktrace : list
A list of namedtuples
(addr, name, offset, is_python)
Higher-level Tools¶
These are high-level tools for sampling the C-stack of a thread.
-
class
stacktrace.tools.Timer(tid, func, interval=0.05, maxdepth=100, show_python=True)[source]¶ A Timer object that repeatedly invoke backtrace on a target thread at a given frequency.
Parameters: - tid : int
Target thread id.
- func : callable
A callback function that takes a single argument. A list of
StackEntrieswill be passed in. It will be called upon every stacktrace with the trace info as a string.- interval : float
Sampling frequency in seconds. Default to 1/20 (i.e. 20Hz). The value is passed to
time.sleep().- maxdepth : int
Maximum stack depth.
- show_python : bool
Whether to filter out python stack entries.
-
class
stacktrace.tools.Profiler(tid, **kwargs)[source]¶ This classs wraps the
stacktrace.tools.Timerfor providing profiling data by processing the stack traces, grouping them and counting their occurances. The data is stored as a dictionary that can be retrieved by using.get_result()or.get_sorted().Parameters: - tid : int
Target thread id.
- **kwargs :
Other keywords arguments to
stacktrace.tools.Timer.
Examples
Use as context-manager:
>>> with Profiler(tid) as prof: ... code_to_be_traced() >>> stacktraces = prof.get_result()
Use with explicit
.start()and.join():>>> prof = Profiler(tid) >>> prof.start() >>> code_to_be_traced() >>> prof.join() >>> stacktraces = prof.get_result()
-
get_result()[source]¶ Get the stacktrace result as a dict.
Examples
Sample data:
{4317941904: {'count': 3, 'name': 'method_get'}, 4318042736: {'count': 1, 'name': 'frame_dealloc'}, 4318048880: {'count': 1, 'name': 'PyFrame_New'}, 4318056128: {'count': 1, 'name': 'PyFunction_NewWithQualName'}}
The first level keys are the symbol address. The first level values are the count that the symbol has appeared on the stack. The name is the name of the symbol, which can be a ‘?’ for unknown symbol (because of lack of debug information).