1SATYR-PYTHON(3) satyr-python SATYR-PYTHON(3)
2
6 satyr-python - satyr python API
7 Contents:
9
11 A Report object represents a single problem report in the uReport for‐
12 mat.
13 class satyr.Report
15 satyr.Report - report containing all data relevant to a software
16 problem
17 Usage:
19 satyr.Report() - creates an empty report object
21 satyr.Report(json_string) - creates a report from its JSON rep‐
23 resentation
24 auth Dictinary of key/value pairs used for authentication
26 component_name
28 Name of the software component this report pertains to
29 (string)
30 operating_system
32 Operating system (OperatingSystem object)
33 packages
35 List of packages (currently a list of RpmPackage objects)
36 report_type
38 Report type (string)
39 report_version
41 Version of the report (int)
42 reporter_name
44 Name of the reporting software (string)
45 reporter_version
47 Version of the reporting software (string)
48 stacktrace
50 Problem stacktrace (SingleThreadStacktrace or Multi‐
51 ThreadStacktrace object)
52 to_json()
54 Usage: report.to_json()
55 Returns: string - the report serialized as JSON
57 user_local
59 Did the problem originate in a program executed by local
60 user? (bool)
61 user_root
63 Did the problem originate in a program running as root?
64 (bool)
65 Operating system
67 Data about operating system are stored in the OperatingSystem object.
68 class satyr.OperatingSystem
70 satyr.OperatingSystem - describes an operating system
71 Usage:
73 satyr.OperatingSystem() - creates an empty operating system
75 object
76 satyr.OperatingSystem(name, version, arch) - creates an operat‐
78 ing system object with given properties (all arguments are
79 strings or None)
80 architecture
82 Architecture (string)
83 cpe Common platform enumeration identifier (string)
85 name Operating system name (string)
87 uptime Machine uptime (long)
89 version
91 Version (string)
92 Package
94 The Report can contain a list of software packages. Currently, only RPM
95 packages are supported.
96 class satyr.RpmPackage
98 satyr.RpmPackage - RPM package representation
99 Usage:
101 satyr.RpmPackage() - creates an empty RPM package object
103 satyr.RpmPackage(name, epoch, version, release, arch) - creates
105 RPM package object with given properties
106 architecture
108 Architecture (string)
109 epoch Epoch (int)
111 install_time
113 Time of installation (long)
114 name Package name (string)
116 release
118 Release (string)
119 role Role the package plays in the problem. Currently
121 ROLE_UNKNOWN or ROLE_AFFECTED.
122 version
124 Version (string)
125
127 Each problem has its own frame, stacktrace and thread type (for prob‐
128 lems that can have multiple threads).
129 WARNING:
131 The GdbFrame, GdbThread, and GdbStacktrace have rather limited func‐
132 tionality, cannot be used in reports, and will probably be removed
133 in the future.
134 Frame classes
136 Stack frame corresponds to a function invocation saved on the stack.
137 All frame types are derived from the BaseFrame.
138 BaseFrame
140 class satyr.BaseFrame
141 satyr.BaseFrame - base class for call frames
142 equals()
144 Usage: frame.equals(otherframe)
145 Returns: bool - True if frame has attributes equal to
147 otherframe
148 short_string()
150 Usage: frame.short_string()
151 Returns: string - brief textual representation of the
153 frame
154 CoreFrame
156 class satyr.CoreFrame
157 satyr.CoreFrame - class representing a frame in a native exe‐
158 cutable
159 Usage: satyr.CoreFrame() - creates an empty frame
161 address
163 Address of the machine code in memory (long)
164 build_id
166 Build ID of the ELF file (string)
167 build_id_offset
169 Offset of the instruction pointer from the start of the
170 executable segment (long)
171 dup() Usage: frame.dup()
173 Returns: satyr.CoreFrame - a new clone of the frame
175 Clones the frame object. All new structures are indepen‐
177 dent of the original object.
178 file_name
180 Name of the executable or shared library (string)
181 fingerprint
183 Fingerprint of the current function (string)
184 fingerprint_hashed
186 True if fingerprint is already hashed (bool)
187 function_name
189 Function name (string)
190 JavaFrame
192 class satyr.JavaFrame
193 satyr.JavaFrame - class representing a java frame
194 Usage:
196 satyr.JavaFrame() - creates an empty frame
198 satyr.JavaFrame(str) - parses str and fills the frame object
200 class_path
202 Class path (string)
203 dup() Usage: frame.dup()
205 Returns: satyr.JavaFrame - a new clone of frame
207 Clones the frame object. All new structures are indepen‐
209 dent of the original object.
210 file_line
212 File line (positive integer)
213 file_name
215 File name (string)
216 is_exception
218 True if frame is an exception frame (bool)
219 is_native
221 True if method is native, always false if frame is an
222 exception (bool)
223 message
225 Exception message (string)
226 name Fully qualified domain name (string)
228 KerneloopsFrame
230 class satyr.KerneloopsFrame
231 satyr.KerneloopsFrame - class representing a frame in a ker‐
232 neloops
233 Usage:
235 satyr.KerneloopsFrame() - creates an empty frame
237 satyr.KerneloopsFrame(str) - parses str and fills the frame
239 object
240 address
242 Address of the current instruction (long)
243 dup() Usage: frame.dup()
245 Returns: satyr.KerneloopsFrame - a new clone of frame
247 Clones the frame object. All new structures are indepen‐
249 dent of the original object.
250 from_address
252 Address of the caller's instruction (long)
253 from_function_length
255 Caller function length (long)
256 from_function_name
258 Caller function name (string)
259 from_function_offset
261 Caller function offset (long)
262 from_module_name
264 Module owning the caller function (string)
265 function_length
267 Function length (long)
268 function_name
270 Function name (string)
271 function_offset
273 Function offset (long)
274 module_name
276 Module owning the function (string)
277 reliable
279 True if the the frame is guaranteed to be real (bool)
280 special_stack
282 Identifier of x86_64 kernel stack (string)
283 PythonFrame
285 class satyr.PythonFrame
286 satyr.PythonFrame - class representing a python frame
287 Usage:
289 satyr.PythonFrame() - creates an empty frame
291 satyr.PythonFrame(str) - parses str and fills the frame object
293 dup() Usage: frame.dup()
295 Returns: satyr.PythonFrame - a new clone of frame
297 Clones the frame object. All new structures are indepen‐
299 dent of the original object.
300 file_line
302 Source line number (positive integer)
303 file_name
305 Source file name (string)
306 function_name
308 Function name (string)
309 line_contents
311 Remaining line contents (string)
312 special_file
314 True if the frame is not a real file, like stdin or
315 eval'd string (bool)
316 special_function
318 True if the frame doesn't belong to a named function,
319 e.g. lambda or a module
320 GdbFrame
322 class satyr.GdbFrame
323 satyr.GdbFrame - class representing a frame in a thread
324 Usage:
326 satyr.GdbFrame() - creates an empty frame
328 satyr.GdbFrame(str) - parses str and fills the frame object
330 address
332 Address of the current instruction (long)
333 calls_func()
335 Usage: frame.calls_func(name)
336 name: string - function name
338 Returns: integer - 0 = False, 1 = True
340 Checks whether the frame represents a call to a function
342 with given name.
343 calls_func_in_file()
345 Usage: frame.calls_func_in_file(name, filename)
346 name: string - function name
348 filename: string - file name
350 Returns: integer - 0 = False, 1 = True
352 Checks whether the frame represents a call to a function
354 with given name from a given file.
355 dup() Usage: frame.dup()
357 Returns: satyr.GdbFrame - a new clone of the frame
359 Clones the frame object. All new structures are indepen‐
361 dent of the original object.
362 function_name
364 Function name (string)
365 function_type
367 Function type (string)
368 library_name
370 Executable file name (string)
371 number Frame number (positive integer)
373 signal_handler_called
375 True if the frame is signal handler (bool)
376 source_file
378 Source file name (string)
379 source_line
381 Source line number (positive integer)
382 Thread classes
384 Thread classes are defined only for problems that can have multiple
385 thread. They all have BaseThread as a base class.
386 BaseThread
388 class satyr.BaseThread
389 satyr.BaseThread - base class for threads
390 distance()
392 Usage: thread.distance(other, dist_type=DISTANCE_LEVEN‐
393 SHTEIN)
394 other: other thread
396 dist_type (optional): one of DISTANCE_LEVENSHTEIN, DIS‐
398 TANCE_JARO_WINKLER, DISTANCE_JACCARD or DISTANCE_DAM‐
399 ERAU_LEVENSHTEIN
400 Returns: positive float - distance between the two
402 threads
403 equals()
405 Usage: frame.equals(otherthread)
406 Returns: bool - True if thread has attributes equal to
408 otherthread
409 frames A list containing objects representing frames in a
411 thread.
412 get_duphash()
414 Usage: thread.get_duphash(frames=0, flags=DUPHASH_NORMAL,
415 prefix='')
416 Returns: string - thread's duplication hash
418 frames: integer - number of frames to use (default 0
420 means use all)
421 flags: integer - bitwise sum of flags (DUPHASH_NORMAL,
423 DUPHASH_NOHASH, DUPHASH_NONORMALIZE, DUPHASH_KOOPS_COM‐
424 PAT)
425 prefix: string - string to be prepended in front of the
427 text before hashing
428 CoreThread
430 class satyr.CoreThread
431 satyr.CoreThread - class representing a thread in a stacktrace
432 Usage: satyr.CoreThread() - creates an empty thread
434 dup() Usage: thread.dup()
436 Returns: satyr.CoreThread - a new clone of thread
438 Clones the thread object. All new structures are indepen‐
440 dent of the original object.
441 JavaThread
443 class satyr.JavaThread
444 satyr.JavaThread - class representing a thread in a stacktrace
445 Usage:
447 satyr.JavaThread() - creates an empty thread
449 satyr.JavaThread(str) - parses str and fills the thread object
451 dup() Usage: thread.dup()
453 Returns: satyr.JavaThread - a new clone of thread
455 Clones the thread object. All new structures are indepen‐
457 dent of the original object.
458 format_funs()
460 Usage: thread.format_funs()
461 Returns: string
463 name Thread name (string)
465 quality()
467 Usage: thread.quality()
468 Returns: float - 0..1, thread quality
470 Computes the ratio #good / #all. See quality_counts
472 method for more.
473 quality_counts()
475 Usage: thread.quality_counts()
476 Returns: tuple (ok, all) - ok representing number of
478 'good' frames, all representing total number of frames
479 Counts the number of 'good' frames and the number of all
481 frames. 'Good' means the function name is known (not just
482 '??').
483 GdbThread
485 class satyr.GdbThread
486 satyr.GdbThread - class representing a thread in a stacktrace
487 Usage:
489 satyr.GdbThread() - creates an empty thread
491 satyr.GdbThread(str) - parses str and fills the thread object
493 satyr.GdbThread(str, only_funs=True) - parses list of function
495 names
496 dup() Usage: thread.dup()
498 Returns: satyr.GdbThread - a new clone of thread
500 Clones the thread object. All new structures are indepen‐
502 dent of the original object.
503 format_funs()
505 Usage: thread.format_funs()
506 Returns: string
508 number Thread number (positive integer)
510 quality()
512 Usage: thread.quality()
513 Returns: float - 0..1, thread quality
515 Computes the ratio #good / #all. See quality_counts
517 method for more.
518 quality_counts()
520 Usage: thread.quality_counts()
521 Returns: tuple (ok, all) - ok representing number of
523 'good' frames, all representing total number of frames
524 Counts the number of 'good' frames and the number of all
526 frames. 'Good' means the function name is known (not just
527 '??').
528 Stacktrace classes
530 Single threaded stacktraces have SingleThreadStacktrace as their base
531 class, which is in turn derived from BaseThread. This means that Sin‐
532 gleThreadStacktrace can be treated as a thread:
533 · Kerneloops
535 · PythonStacktrace
537 Stacktrace types with the possibility of multiple threads are derived
539 from MultiThreadStacktrace:
540 · CoreStacktrace
542 · JavaStacktrace
544 · GdbStacktrace
546 SingleThreadStacktrace
548 class satyr.SingleThreadStacktrace
549 satyr.SingleThreadStacktrace - base class for stacktrace with
550 single thread
551 crash_thread
553 Reference to the thread that caused the crash, if known
554 static from_json()
556 Usage: SomeStacktrace.from_json(json_string) (class
557 method)
558 Returns: stacktrace (of SomeStacktrace class) deserial‐
560 ized from json_string
561 json_string: string - json input
563 get_bthash()
565 Usage: stacktrace.get_bthash([flags])
566 Returns: string - hash of the stacktrace
568 flags: integer - bitwise sum of flags (BTHASH_NORMAL,
570 BTHASH_NOHASH)
571 to_short_text()
573 Usage: stacktrace.to_short_text([max_frames])
574 Returns short text representation of the stacktrace. If
576 max_frames is specified, the result includes only that
577 much topmost frames.
578 MultiThreadStacktrace
580 class satyr.MultiThreadStacktrace
581 satyr.MultiThreadStacktrace - base class for stacktrace with
582 multiple threads
583 crash_thread
585 Reference to the thread that caused the crash, if known
586 static from_json()
588 Usage: SomeStacktrace.from_json(json_string) (class
589 method)
590 Returns: stacktrace (of SomeStacktrace class) deserial‐
592 ized from json_string
593 json_string: string - json input
595 get_bthash()
597 Usage: stacktrace.get_bthash([flags])
598 Returns: string - hash of the stacktrace
600 flags: integer - bitwise sum of flags (BTHASH_NORMAL,
602 BTHASH_NOHASH)
603 threads
605 A list containing the objects representing threads in the
606 stacktrace.
607 to_short_text()
609 Usage: stacktrace.to_short_text([max_frames])
610 Returns short text representation of the stacktrace. If
612 max_frames is specified, the result includes only that
613 much topmost frames.
614 CoreStacktrace
616 class satyr.CoreStacktrace
617 satyr.CoreStacktrace - class representing a core stacktrace
618 Usage:
620 satyr.CoreStacktrace() - creates an empty stacktrace
622 satyr.CoreStacktrace(json) - creates stacktrace object from JSON
624 string
625 dup() Usage: stacktrace.dup()
627 Returns: satyr.CoreStacktrace - a new clone of core
629 stacktrace
630 Clones the stacktrace object. All new structures are
632 independent of the original object.
633 executable
635 Name of the executable (string)
636 signal Signal number (int)
638 JavaStacktrace
640 class satyr.JavaStacktrace
641 satyr.JavaStacktrace - class representing a java stacktrace
642 Usage:
644 satyr.JavaStacktrace() - creates an empty stacktrace
646 satyr.JavaStacktrace(str) - parses str and fills the stacktrace
648 object
649 dup() Usage: stacktrace.dup()
651 Returns: satyr.JavaStacktrace - a new clone of java
653 stacktrace
654 Clones the stacktrace object. All new structures are
656 independent of the original object.
657 Kerneloops
659 class satyr.Kerneloops
660 satyr.Kerneloops - class representing a kerneloops stacktrace
661 Usage:
663 satyr.Kerneloops() - creates an empty kerneloops stacktrace
665 satyr.Kerneloops(str) - parses str and fills the kerneloops
667 stacktrace object
668 dup() Usage: stacktrace.dup()
670 Returns: satyr.Kerneloops - a new clone of kerneloops
672 stacktrace
673 Clones the kerneloops object. All new structures are
675 independent of the original object.
676 modules
678 Modules loaded at the time of the event (list of strings)
679 normalize()
681 Usage: stacktrace.normalize()
682 Normalizes the stacktrace.
684 raw_oops
686 Original text of the kerneloops (string)
687 taint_flags
689 Dictionary of kernel taint flags. Keys are the flag
690 names, values are booleans indicating whether the flag is
691 set.
692 version
694 Kernel version (string)
695 PythonStacktrace
697 class satyr.PythonStacktrace
698 satyr.PythonStacktrace - class representing a python stacktrace
699 Usage:
701 satyr.PythonStacktrace() - creates an empty python stacktrace
703 satyr.PythonStacktrace(str) - parses str and fills the python
705 stacktrace object
706 dup() Usage: stacktrace.dup()
708 Returns: satyr.PythonStacktrace - a new clone of python
710 stacktrace
711 Clones the PythonStacktrace object. All new structures
713 are independent of the original object.
714 exception_name
716 Exception type (string)
717 GdbStacktrace
719 class satyr.GdbStacktrace
720 satyr.GdbStacktrace - class representing a stacktrace
721 Usage:
723 satyr.GdbStacktrace() - creates an empty stacktrace
725 satyr.GdbStacktrace(str) - parses str and fills the stacktrace
727 object
728 crashframe
730 Readonly. By default the field contains None. After call‐
731 ing the find_crash_frame method, a reference to
732 satyr.Frame object is stored into the field.
733 dup() Usage: stacktrace.dup()
735 Returns: satyr.GdbStacktrace - a new clone of stacktrace
737 Clones the stacktrace object. All new structures are
739 independent of the original object.
740 find_address()
742 Usage: stacktrace.find_address(address)
743 address: long - address to find
745 Returns: satyr.Sharedlib object or None if not found
747 Looks whether the given address belongs to a shared
749 library.
750 find_crash_frame()
752 Usage: stacktrace.find_crash_frame()
753 Returns: satyr.Frame - crash frame
755 Finds crash frame in the stacktrace. Also sets the stack‐
757 trace.crashframe field.
758 libs A list containing the satyr.Sharedlib objects represent‐
760 ing shared libraries loaded at the moment of crash.
761 limit_frame_depth()
763 Usage: stacktrace.limit_frame_depth(N)
764 N: positive integer - frame depth
766 Crops all threads to only contain first N frames.
768 normalize()
770 Usage: stacktrace.normalize()
771 Normalizes all threads in the stacktrace.
773 quality_complex()
775 Usage: stacktrace.quality_complex()
776 Returns: float - 0..1, stacktrace quality
778 Computes the quality from stacktrace, crash thread and
780 frames around the crash.
781 quality_simple()
783 Usage: stacktrace.quality_simple()
784 Returns: float - 0..1, stacktrace quality
786 Computes the quality from stacktrace itself.
788 set_libnames()
790 Usage: stacktrace.set_libnames()
791 Sets library names according to sharedlibs data.
793 to_short_text()
795 Usage: stacktrace.to_short_text([max_frames])
796 Returns short text representation of the crash thread. If
798 max_frames is specified, the result includes only that
799 much topmost frames.
800
802 Distance matrix
803 class satyr.Distances
804 satyr.Distances - class representing distances between objects
805 Usage:
807 satyr.Distances(m, n) - creates an m-by-n distance matrix
809 satyr.Distances([threads], m, dist_type=DISTANCE_LEVENSHTEIN) -
811 compares first m threads with others
812 dist_type (optional): DISTANCE_LEVENSHTEIN, DISTANCE_JACCARD or
814 DISTANCE_DAMERAU_LEVENSHTEIN
815 dup() Usage: distances.dup()
817 Returns: satyr.Distances - a new clone of the distances
819 Clones the distances object. All new structures are inde‐
821 pendent of the original object.
822 get_distance()
824 Usage: distances.get_distance(i, j)
825 Returns: positive float - distance between objects i and
827 j
828 get_size()
830 Usage: distances.get_size()
831 Returns: (m, n) - size of the distance matrix
833 set_distance()
835 Usage: distances.set_distance(i, j, d)
836 Sets distance between objects i and j to d
838 Dendrogram
840 class satyr.Dendrogram
841 satyr.Dendrogram - a dendrogram created by clustering algorithm
842 Usage: satyr.Dendrogram(distances) - creates new dendrogram from
844 a distance matrix
845 cut() Usage: dendrogram.cut(level, min_size)
847 Returns: list of clusters (lists of objects) which have
849 at least min_size objects and which were merged at most
850 at the specified distance
851 get_merge_level()
853 Usage: dendrogram.get_merge_level(i)
854 Returns: float - merge level between clusters at posi‐
856 tions i and i + 1
857 get_object()
859 Usage: dendrogram.get_object(i)
860 Returns: integer - index of the object at position i
862 get_size()
864 Usage: dendrogram.get_size()
865 Returns: integer - number of objects in the dendrogram
867 · genindex
869 · modindex
871 · search
873
875 Red Hat, Inc
876
878 2013, Red Hat, Inc
879satyr 0.13 October 30, 2018 SATYR-PYTHON(3)