satyr-python-2(3)
satyr-python – satyr python API
Contents:
Report
A Report object represents a single problem report in the uReport format.
class satyr.Report- satyr.Report – report containing all data relevant to a software problem
auth- Dictinary of key/value pairs used for authentication
component_name- Name of the software component this report pertains to (string)
operating_system- Operating system (
OperatingSystemobject) packages- List of packages (currently a list of
RpmPackageobjects) report_type- Report type (string)
report_version- Version of the report (int)
reporter_name- Name of the reporting software (string)
reporter_version- Version of the reporting software (string)
stacktrace- Problem stacktrace (
SingleThreadStacktraceorMultiThreadStacktraceobject) to_json()- Usage: report.to_json()
user_local- Did the problem originate in a program executed by local user? (bool)
user_root- Did the problem originate in a program running as root? (bool)
Usage:
satyr.Report() – creates an empty report object
satyr.Report(json_string) – creates a report from its JSON representation
Returns: string – the report serialized as JSON
Operating system
Data about operating system are stored in the OperatingSystem object.
class satyr.OperatingSystem- satyr.OperatingSystem – describes an operating system
architecture- Architecture (string)
cpe- Common platform enumeration identifier (string)
name- Operating system name (string)
uptime- Machine uptime (long)
version- Version (string)
Usage:
satyr.OperatingSystem() – creates an empty operating system object
satyr.OperatingSystem(name, version, arch) – creates an operating system object with given properties (all arguments are strings or None)
Package
The Report can contain a list of software packages. Currently, only RPM packages are supported.
class satyr.RpmPackage- satyr.RpmPackage – RPM package representation
architecture- Architecture (string)
epoch- Epoch (int)
install_time- Time of installation (long)
name- Package name (string)
release- Release (string)
role- Role the package plays in the problem. Currently ROLE_UNKNOWN or ROLE_AFFECTED.
version- Version (string)
Usage:
satyr.RpmPackage() – creates an empty RPM package object
satyr.RpmPackage(name, epoch, version, release, arch) – creates RPM package object with given properties
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
equals()- Usage: frame.equals(otherframe)
short_string()- Usage: frame.short_string()
Returns: bool – True if frame has attributes equal to otherframe
Returns: string – brief textual representation of the frame
CoreFrame
class satyr.CoreFrame- satyr.CoreFrame – class representing a frame in a native executable
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()
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)
Usage: satyr.CoreFrame() – creates an empty frame
Returns: satyr.CoreFrame – a new clone of the frame
Clones the frame object. All new structures are independent of the original object.
JavaFrame
class satyr.JavaFrame- satyr.JavaFrame – class representing a java frame
class_path- Class path (string)
dup()- Usage: frame.dup()
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)
Usage:
satyr.JavaFrame() – creates an empty frame
satyr.JavaFrame(str) – parses str and fills the frame object
Returns: satyr.JavaFrame – a new clone of frame
Clones the frame object. All new structures are independent of the original object.
KerneloopsFrame
class satyr.KerneloopsFrame- satyr.KerneloopsFrame – class representing a frame in a kerneloops
address- Address of the current instruction (long)
dup()- Usage: frame.dup()
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)
special_stack- Identifier of x86_64 kernel stack (string)
Usage:
satyr.KerneloopsFrame() – creates an empty frame
satyr.KerneloopsFrame(str) – parses str and fills the frame object
Returns: satyr.KerneloopsFrame – a new clone of frame
Clones the frame object. All new structures are independent of the original object.
PythonFrame
class satyr.PythonFrame- satyr.PythonFrame – class representing a python frame
dup()- Usage: frame.dup()
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
Usage:
satyr.PythonFrame() – creates an empty frame
satyr.PythonFrame(str) – parses str and fills the frame object
Returns: satyr.PythonFrame – a new clone of frame
Clones the frame object. All new structures are independent of the original object.
GdbFrame
class satyr.GdbFrame- satyr.GdbFrame – class representing a frame in a thread
address- Address of the current instruction (long)
calls_func()- Usage: frame.calls_func(name)
calls_func_in_file()- Usage: frame.calls_func_in_file(name, filename)
dup()- Usage: frame.dup()
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)
Usage:
satyr.GdbFrame() – creates an empty frame
satyr.GdbFrame(str) – parses str and fills the frame object
name: string – function name
Returns: integer – 0 = False, 1 = True
Checks whether the frame represents a call to a function with given name.
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.
Returns: satyr.GdbFrame – a new clone of the frame
Clones the frame object. All new structures are independent of the original object.
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)
equals()- Usage: frame.equals(otherthread)
frames- A list containing objects representing frames in a thread.
get_duphash()- Usage: thread.get_duphash(frames=0, flags=DUPHASH_NORMAL, prefix=”)
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
Returns: bool – True if thread has attributes equal to otherthread
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, DUPHASH_KOOPS_COMPAT)
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
dup()- Usage: thread.dup()
Usage: satyr.CoreThread() – creates an empty thread
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
dup()- Usage: thread.dup()
format_funs()- Usage: thread.format_funs()
name- Thread name (string)
quality()- Usage: thread.quality()
quality_counts()- Usage: thread.quality_counts()
Usage:
satyr.JavaThread() – creates an empty thread
satyr.JavaThread(str) – parses str and fills the thread object
Returns: satyr.JavaThread – a new clone of thread
Clones the thread object. All new structures are independent of the original object.
Returns: string
Returns: float – 0..1, thread quality
Computes the ratio #good / #all. See quality_counts method for more.
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
dup()- Usage: thread.dup()
format_funs()- Usage: thread.format_funs()
number- Thread number (positive integer)
quality()- Usage: thread.quality()
quality_counts()- Usage: thread.quality_counts()
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
Returns: satyr.GdbThread – a new clone of thread
Clones the thread object. All new structures are independent of the original object.
Returns: string
Returns: float – 0..1, thread quality
Computes the ratio #good / #all. See quality_counts method for more.
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:
- •
Kerneloops- •
PythonStacktrace- •
CoreStacktrace- •
JavaStacktrace- •
GdbStacktrace
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)
get_bthash()- Usage: stacktrace.get_bthash([flags])
to_short_text()- Usage: stacktrace.to_short_text([max_frames])
Returns: stacktrace (of SomeStacktrace class) deserialized from json_string
json_string: string – json input
Returns: string – hash of the stacktrace
flags: integer – bitwise sum of flags (BTHASH_NORMAL, BTHASH_NOHASH)
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)
get_bthash()- Usage: stacktrace.get_bthash([flags])
threads- A list containing the objects representing threads in the stacktrace.
to_short_text()- Usage: stacktrace.to_short_text([max_frames])
Returns: stacktrace (of SomeStacktrace class) deserialized from json_string
json_string: string – json input
Returns: string – hash of the stacktrace
flags: integer – bitwise sum of flags (BTHASH_NORMAL, BTHASH_NOHASH)
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
dup()- Usage: stacktrace.dup()
executable- Name of the executable (string)
signal- Signal number (int)
Usage:
satyr.CoreStacktrace() – creates an empty stacktrace
satyr.CoreStacktrace(json) – creates stacktrace object from JSON string
Returns: satyr.CoreStacktrace – a new clone of core stacktrace
Clones the stacktrace object. All new structures are independent of the original object.
JavaStacktrace
class satyr.JavaStacktrace- satyr.JavaStacktrace – class representing a java stacktrace
dup()- Usage: stacktrace.dup()
Usage:
satyr.JavaStacktrace() – creates an empty stacktrace
satyr.JavaStacktrace(str) – parses str and fills the stacktrace object
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
dup()- Usage: stacktrace.dup()
modules- Modules loaded at the time of the event (list of strings)
normalize()- Usage: stacktrace.normalize()
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)
Usage:
satyr.Kerneloops() – creates an empty kerneloops stacktrace
satyr.Kerneloops(str) – parses str and fills the kerneloops stacktrace object
Returns: satyr.Kerneloops – a new clone of kerneloops stacktrace
Clones the kerneloops object. All new structures are independent of the original object.
Normalizes the stacktrace.
PythonStacktrace
class satyr.PythonStacktrace- satyr.PythonStacktrace – class representing a python stacktrace
dup()- Usage: stacktrace.dup()
exception_name- Exception type (string)
Usage:
satyr.PythonStacktrace() – creates an empty python stacktrace
satyr.PythonStacktrace(str) – parses str and fills the python stacktrace object
Returns: satyr.PythonStacktrace – a new clone of python stacktrace
Clones the PythonStacktrace object. All new structures are independent of the original object.
GdbStacktrace
class satyr.GdbStacktrace- satyr.GdbStacktrace – class representing a stacktrace
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()
find_address()- Usage: stacktrace.find_address(address)
find_crash_frame()- Usage: stacktrace.find_crash_frame()
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)
normalize()- Usage: stacktrace.normalize()
quality_complex()- Usage: stacktrace.quality_complex()
quality_simple()- Usage: stacktrace.quality_simple()
set_libnames()- Usage: stacktrace.set_libnames()
to_short_text()- Usage: stacktrace.to_short_text([max_frames])
Usage:
satyr.GdbStacktrace() – creates an empty stacktrace
satyr.GdbStacktrace(str) – parses str and fills the stacktrace object
Returns: satyr.GdbStacktrace – a new clone of stacktrace
Clones the stacktrace object. All new structures are independent of the original object.
address: long – address to find
Returns: satyr.Sharedlib object or None if not found
Looks whether the given address belongs to a shared library.
Returns: satyr.Frame – crash frame
Finds crash frame in the stacktrace. Also sets the stacktrace.crashframe field.
N: positive integer – frame depth
Crops all threads to only contain first N frames.
Normalizes all threads in the stacktrace.
Returns: float – 0..1, stacktrace quality
Computes the quality from stacktrace, crash thread and frames around the crash.
Returns: float – 0..1, stacktrace quality
Computes the quality from stacktrace itself.
Sets library names according to sharedlibs data.
Returns short text representation of the crash thread. If max_frames is specified, the result includes only that much topmost frames.
Clustering
Distance matrix
class satyr.Distances- satyr.Distances – class representing distances between objects
dup()- Usage: distances.dup()
get_distance()- Usage: distances.get_distance(i, j)
get_size()- Usage: distances.get_size()
set_distance()- Usage: distances.set_distance(i, j, d)
Usage:
satyr.Distances(m, n) – creates an m-by-n distance matrix
satyr.Distances([threads], m, dist_type=DISTANCE_LEVENSHTEIN) – compares first m threads with others
dist_type (optional): DISTANCE_LEVENSHTEIN, DISTANCE_JACCARD or DISTANCE_DAMERAU_LEVENSHTEIN
Returns: satyr.Distances – a new clone of the distances
Clones the distances object. All new structures are independent of the original object.
Returns: positive float – distance between objects i and j
Returns: (m, n) – size of the distance matrix
Sets distance between objects i and j to d
Dendrogram
class satyr.Dendrogram- satyr.Dendrogram – a dendrogram created by clustering algorithm
cut()- Usage: dendrogram.cut(level, min_size)
get_merge_level()- Usage: dendrogram.get_merge_level(i)
get_object()- Usage: dendrogram.get_object(i)
get_size()- Usage: dendrogram.get_size()
- •
- genindex
- •
- modindex
- •
- search
Usage: satyr.Dendrogram(distances) – creates new dendrogram from a distance matrix
Returns: list of clusters (lists of objects) which have at least min_size objects and which were merged at most at the specified distance
Returns: float – merge level between clusters at positions i and i + 1
Returns: integer – index of the object at position i
Returns: integer – number of objects in the dendrogram
Author
Red Hat, Inc
Copyright
2013, Red Hat, Inc