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)

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 StackEntries will 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.

join()

Stop and wait for the timer-thread to end.

start()

Start the timer.

class stacktrace.tools.Profiler(tid, **kwargs)

This classs wraps the stacktrace.tools.Timer for 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()

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).

get_sorted()

Get results sorted by count.

Returns:

sorted_entries : list

List of 2-tuples, which are in the same format of self.get_result().items().

join()

Stop the profiler

start()

Start the profiler