Stacktrace

Each problem has its own frame, stacktrace and thread type (for problems that can have multiple threads).

Warning

The GdbFrame, GdbThread, and GdbStacktrace have rather limited functionality, cannot be used in reports, and will probably be removed in the future.

Frame classes

Stack frame corresponds to a function invocation saved on the stack. All frame types are derived from the BaseFrame.

BaseFrame

class satyr.BaseFrame

satyr.BaseFrame - base class for call frames

short_string()

Usage: frame.short_string()

Returns: string - brief textual representation of the frame

CoreFrame

class satyr.CoreFrame

satyr.CoreFrame - class representing a frame in a native executable

Usage: satyr.CoreFrame() - creates an empty frame

address

Address of the machine code in memory (long)

build_id

Build ID of the ELF file (string)

build_id_offset

Offset of the instruction pointer from the start of the executable segment (long)

dup()

Usage: frame.dup()

Returns: satyr.CoreFrame - a new clone of the frame

Clones the frame object. All new structures are independent of the original object.

file_name

Name of the executable or shared library (string)

fingerprint

Fingerprint of the current function (string)

fingerprint_hashed

True if fingerprint is already hashed (bool)

function_name

Function name (string)

JavaFrame

class satyr.JavaFrame

satyr.JavaFrame - class representing a java frame

Usage:

satyr.JavaFrame() - creates an empty frame

satyr.JavaFrame(str) - parses str and fills the frame object

class_path

Class path (string)

dup()

Usage: frame.dup()

Returns: satyr.JavaFrame - a new clone of frame

Clones the frame object. All new structures are independent of the original object.

file_line

File line (positive integer)

file_name

File name (string)

is_exception

True if frame is an exception frame (bool)

is_native

True if method is native, always false if frame is an exception (bool)

message

Exception message (string)

name

Fully qualified domain name (string)

KerneloopsFrame

class satyr.KerneloopsFrame

satyr.KerneloopsFrame - class representing a frame in a kerneloops

Usage:

satyr.KerneloopsFrame() - creates an empty frame

satyr.KerneloopsFrame(str) - parses str and fills the frame object

address

Address of the current instruction (long)

dup()

Usage: frame.dup()

Returns: satyr.KerneloopsFrame - a new clone of frame

Clones the frame object. All new structures are independent of the original object.

from_address

Address of the caller’s instruction (long)

from_function_length

Caller function length (long)

from_function_name

Caller function name (string)

from_function_offset

Caller function offset (long)

from_module_name

Module owning the caller function (string)

function_length

Function length (long)

function_name

Function name (string)

function_offset

Function offset (long)

module_name

Module owning the function (string)

reliable

True if the the frame is guaranteed to be real (bool)

PythonFrame

class satyr.PythonFrame

satyr.PythonFrame - class representing a python frame

Usage:

satyr.PythonFrame() - creates an empty frame

satyr.PythonFrame(str) - parses str and fills the frame object

dup()

Usage: frame.dup()

Returns: satyr.PythonFrame - a new clone of frame

Clones the frame object. All new structures are independent of the original object.

file_line

Source line number (positive integer)

file_name

Source file name (string)

function_name

Function name (string)

line_contents

Remaining line contents (string)

special_file

True if the frame is not a real file, like stdin or eval’d string (bool)

special_function

True if the frame doesn’t belong to a named function, e.g. lambda or a module

GdbFrame

class satyr.GdbFrame

satyr.GdbFrame - class representing a frame in a thread

Usage:

satyr.GdbFrame() - creates an empty frame

satyr.GdbFrame(str) - parses str and fills the frame object

address

Address of the current instruction (long)

calls_func()

Usage: frame.calls_func(name)

name: string - function name

Returns: integer - 0 = False, 1 = True

Checks whether the frame represents a call to a function with given name.

calls_func_in_file()

Usage: frame.calls_func_in_file(name, filename)

name: string - function name

filename: string - file name

Returns: integer - 0 = False, 1 = True

Checks whether the frame represents a call to a function with given name from a given file.

dup()

Usage: frame.dup()

Returns: satyr.GdbFrame - a new clone of the frame

Clones the frame object. All new structures are independent of the original object.

function_name

Function name (string)

function_type

Function type (string)

library_name

Executable file name (string)

number

Frame number (positive integer)

signal_handler_called

True if the frame is signal handler (bool)

source_file

Source file name (string)

source_line

Source line number (positive integer)

Thread classes

Thread classes are defined only for problems that can have multiple thread. They all have BaseThread as a base class.

BaseThread

class satyr.BaseThread

satyr.BaseThread - base class for threads

distance()

Usage: thread.distance(other, dist_type=DISTANCE_LEVENSHTEIN)

other: other thread

dist_type (optional): one of DISTANCE_LEVENSHTEIN, DISTANCE_JARO_WINKLER, DISTANCE_JACCARD or DISTANCE_DAMERAU_LEVENSHTEIN

Returns: positive float - distance between the two threads

frames

A list containing objects representing frames in a thread.

get_duphash()

Usage: thread.get_duphash(frames=0, flags=DUPHASH_NORMAL, prefix=’‘)

Returns: string - thread’s duplication hash

frames: integer - number of frames to use (default 0 means use all)

flags: integer - bitwise sum of flags (DUPHASH_NORMAL, DUPHASH_NOHASH, DUPHASH_NONORMALIZE)

prefix: string - string to be prepended in front of the text before hashing

CoreThread

class satyr.CoreThread

satyr.CoreThread - class representing a thread in a stacktrace

Usage: satyr.CoreThread() - creates an empty thread

dup()

Usage: thread.dup()

Returns: satyr.CoreThread - a new clone of thread

Clones the thread object. All new structures are independent of the original object.

JavaThread

class satyr.JavaThread

satyr.JavaThread - class representing a thread in a stacktrace

Usage:

satyr.JavaThread() - creates an empty thread

satyr.JavaThread(str) - parses str and fills the thread object

dup()

Usage: thread.dup()

Returns: satyr.JavaThread - a new clone of thread

Clones the thread object. All new structures are independent of the original object.

format_funs()

Usage: thread.format_funs()

Returns: string

name

Thread name (string)

quality()

Usage: thread.quality()

Returns: float - 0..1, thread quality

Computes the ratio #good / #all. See quality_counts method for more.

quality_counts()

Usage: thread.quality_counts()

Returns: tuple (ok, all) - ok representing number of ‘good’ frames, all representing total number of frames

Counts the number of ‘good’ frames and the number of all frames. ‘Good’ means the function name is known (not just ‘??’).

GdbThread

class satyr.GdbThread

satyr.GdbThread - class representing a thread in a stacktrace

Usage:

satyr.GdbThread() - creates an empty thread

satyr.GdbThread(str) - parses str and fills the thread object

satyr.GdbThread(str, only_funs=True) - parses list of function names

dup()

Usage: thread.dup()

Returns: satyr.GdbThread - a new clone of thread

Clones the thread object. All new structures are independent of the original object.

format_funs()

Usage: thread.format_funs()

Returns: string

number

Thread number (positive integer)

quality()

Usage: thread.quality()

Returns: float - 0..1, thread quality

Computes the ratio #good / #all. See quality_counts method for more.

quality_counts()

Usage: thread.quality_counts()

Returns: tuple (ok, all) - ok representing number of ‘good’ frames, all representing total number of frames

Counts the number of ‘good’ frames and the number of all frames. ‘Good’ means the function name is known (not just ‘??’).

Stacktrace classes

Single threaded stacktraces have SingleThreadStacktrace as their base class, which is in turn derived from BaseThread. This means that SingleThreadStacktrace can be treated as a thread:

Stacktrace types with the possibility of multiple threads are derived from MultiThreadStacktrace:

SingleThreadStacktrace

class satyr.SingleThreadStacktrace

satyr.SingleThreadStacktrace - base class for stacktrace with single thread

crash_thread

Reference to the thread that caused the crash, if known

static from_json()

Usage: SomeStacktrace.from_json(json_string) (class method)

Returns: stacktrace (of SomeStacktrace class) deserialized from json_string

json_string: string - json input

get_bthash()

Usage: stacktrace.get_bthash([flags])

Returns: string - hash of the stacktrace

flags: integer - bitwise sum of flags (BTHASH_NORMAL, BTHASH_NOHASH)

to_short_text()

Usage: stacktrace.to_short_text([max_frames])

Returns short text representation of the stacktrace. If max_frames is specified, the result includes only that much topmost frames.

MultiThreadStacktrace

class satyr.MultiThreadStacktrace

satyr.MultiThreadStacktrace - base class for stacktrace with multiple threads

crash_thread

Reference to the thread that caused the crash, if known

static from_json()

Usage: SomeStacktrace.from_json(json_string) (class method)

Returns: stacktrace (of SomeStacktrace class) deserialized from json_string

json_string: string - json input

get_bthash()

Usage: stacktrace.get_bthash([flags])

Returns: string - hash of the stacktrace

flags: integer - bitwise sum of flags (BTHASH_NORMAL, BTHASH_NOHASH)

threads

A list containing the objects representing threads in the stacktrace.

to_short_text()

Usage: stacktrace.to_short_text([max_frames])

Returns short text representation of the stacktrace. If max_frames is specified, the result includes only that much topmost frames.

CoreStacktrace

class satyr.CoreStacktrace

satyr.CoreStacktrace - class representing a core stacktrace

Usage:

satyr.CoreStacktrace() - creates an empty stacktrace

satyr.CoreStacktrace(json) - creates stacktrace object from JSON string

dup()

Usage: stacktrace.dup()

Returns: satyr.CoreStacktrace - a new clone of core stacktrace

Clones the stacktrace object. All new structures are independent of the original object.

executable

Name of the executable (string)

signal

Signal number (int)

JavaStacktrace

class satyr.JavaStacktrace

satyr.JavaStacktrace - class representing a java stacktrace

Usage:

satyr.JavaStacktrace() - creates an empty stacktrace

satyr.JavaStacktrace(str) - parses str and fills the stacktrace object

dup()

Usage: stacktrace.dup()

Returns: satyr.JavaStacktrace - a new clone of java stacktrace

Clones the stacktrace object. All new structures are independent of the original object.

Kerneloops

class satyr.Kerneloops

satyr.Kerneloops - class representing a kerneloops stacktrace

Usage:

satyr.Kerneloops() - creates an empty kerneloops stacktrace

satyr.Kerneloops(str) - parses str and fills the kerneloops stacktrace object

dup()

Usage: stacktrace.dup()

Returns: satyr.Kerneloops - a new clone of kerneloops stacktrace

Clones the kerneloops object. All new structures are independent of the original object.

modules

Modules loaded at the time of the event (list of strings)

normalize()

Usage: stacktrace.normalize()

Normalizes the stacktrace.

raw_oops

Original text of the kerneloops (string)

taint_flags

Dictionary of kernel taint flags. Keys are the flag names, values are booleans indicating whether the flag is set.

version

Kernel version (string)

PythonStacktrace

class satyr.PythonStacktrace

satyr.PythonStacktrace - class representing a python stacktrace

Usage:

satyr.PythonStacktrace() - creates an empty python stacktrace

satyr.PythonStacktrace(str) - parses str and fills the python stacktrace object

dup()

Usage: stacktrace.dup()

Returns: satyr.PythonStacktrace - a new clone of python stacktrace

Clones the PythonStacktrace object. All new structures are independent of the original object.

exception_name

Exception type (string)

GdbStacktrace

class satyr.GdbStacktrace

satyr.GdbStacktrace - class representing a stacktrace

Usage:

satyr.GdbStacktrace() - creates an empty stacktrace

satyr.GdbStacktrace(str) - parses str and fills the stacktrace object

crashframe

Readonly. By default the field contains None. After calling the find_crash_frame method, a reference to satyr.Frame object is stored into the field.

dup()

Usage: stacktrace.dup()

Returns: satyr.GdbStacktrace - a new clone of stacktrace

Clones the stacktrace object. All new structures are independent of the original object.

find_address()

Usage: stacktrace.find_address(address)

address: long - address to find

Returns: satyr.Sharedlib object or None if not found

Looks whether the given address belongs to a shared library.

find_crash_frame()

Usage: stacktrace.find_crash_frame()

Returns: satyr.Frame - crash frame

Finds crash frame in the stacktrace. Also sets the stacktrace.crashframe field.

libs

A list containing the satyr.Sharedlib objects representing shared libraries loaded at the moment of crash.

limit_frame_depth()

Usage: stacktrace.limit_frame_depth(N)

N: positive integer - frame depth

Crops all threads to only contain first N frames.

normalize()

Usage: stacktrace.normalize()

Normalizes all threads in the stacktrace.

quality_complex()

Usage: stacktrace.quality_complex()

Returns: float - 0..1, stacktrace quality

Computes the quality from stacktrace, crash thread and frames around the crash.

quality_simple()

Usage: stacktrace.quality_simple()

Returns: float - 0..1, stacktrace quality

Computes the quality from stacktrace itself.

set_libnames()

Usage: stacktrace.set_libnames()

Sets library names according to sharedlibs data.

to_short_text()

Usage: stacktrace.to_short_text([max_frames])

Returns short text representation of the crash thread. If max_frames is specified, the result includes only that much topmost frames.