satyr-python (3) - Linux Manuals

satyr-python: satyr python API

NAME

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

Usage:

satyr.Report() - creates an empty report object

satyr.Report(json_string) - creates a report from its JSON representation

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 (OperatingSystem object)
packages
List of packages (currently a list of RpmPackage objects)
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 (SingleThreadStacktrace or MultiThreadStacktrace object)
to_json()
Usage: report.to_json()

Returns: string - the report serialized as 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)

Operating system

Data about operating system are stored in the OperatingSystem object.

class satyr.OperatingSystem
satyr.OperatingSystem - describes an operating system

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)

architecture
Architecture (string)
cpe
Common platform enumeration identifier (string)
name
Operating system name (string)
uptime
Machine uptime (long)
version
Version (string)

Package

The Report can contain a list of software packages. Currently, only RPM packages are supported.

class satyr.RpmPackage
satyr.RpmPackage - RPM package representation

Usage:

satyr.RpmPackage() - creates an empty RPM package object

satyr.RpmPackage(name, epoch, version, release, arch) - creates RPM package object with given properties

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)

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)

Returns: bool - True if frame has attributes equal to otherframe

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)
special_stack
Identifier of x86_64 kernel stack (string)

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

equals()
Usage: frame.equals(otherthread)

Returns: bool - True if thread has attributes equal to otherthread

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, 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

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:

•
Kerneloops
•
PythonStacktrace

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

•
CoreStacktrace
•
JavaStacktrace
•
GdbStacktrace

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.

CLUSTERING

Distance matrix

class satyr.Distances
satyr.Distances - class representing distances between objects

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

dup()
Usage: distances.dup()

Returns: satyr.Distances - a new clone of the distances

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

get_distance()
Usage: distances.get_distance(i, j)

Returns: positive float - distance between objects i and j

get_size()
Usage: distances.get_size()

Returns: (m, n) - size of the distance matrix

set_distance()
Usage: distances.set_distance(i, j, d)

Sets distance between objects i and j to d

Dendrogram

class satyr.Dendrogram
satyr.Dendrogram - a dendrogram created by clustering algorithm

Usage: satyr.Dendrogram(distances) - creates new dendrogram from a distance matrix

cut()
Usage: dendrogram.cut(level, min_size)

Returns: list of clusters (lists of objects) which have at least min_size objects and which were merged at most at the specified distance

get_merge_level()
Usage: dendrogram.get_merge_level(i)

Returns: float - merge level between clusters at positions i and i + 1

get_object()
Usage: dendrogram.get_object(i)

Returns: integer - index of the object at position i

get_size()
Usage: dendrogram.get_size()

Returns: integer - number of objects in the dendrogram

•
genindex
•
modindex
•
search

AUTHOR

Red Hat, Inc

COPYRIGHT

2013, Red Hat, Inc

Pages related to satyr-python