Docs: update debuginfo doc
[babeltrace.git] / doc / python-howto.txt
1 PYTHON BINDINGS
2 ----------------
3
4 This is a brief howto for using the Babeltrace Python module.
5
6
7 INSTALLATION:
8
9 By default, the Python bindings are not generated.
10 If you wish to generate and install the Python bindings, you can use the
11 --enable-python-bindings configure option.
12
13 $ ./configure --enable-python-bindings
14
15 The Python module is automatically generated using SWIG, therefore the
16 swig2.0 package on Debian/Ubuntu is requied.
17
18
19 USAGE:
20
21 Once installed, the Python module can be used by importing it in Python.
22 In the Python interpreter:
23
24 >>> import babeltrace
25
26 Then the starting point is to create a context and add a trace to it.
27
28 >>> ctx = babeltrace.Context()
29 >>> ctx.add_trace("path/to/trace", <format>)
30
31 Where <format> is a string containing the format name in which the trace
32 was produced. To print a list of available formats to the standard
33 output, it is possible to use the print_format_list function.
34
35 >>> out = babeltrace.File(None) # This returns stdout
36 >>> babeltrace.print_format_list(out)
37
38 When a trace is added to a context, it is opened and ready to read using
39 an iterator. While creating an iterator, optional starting and ending
40 position may be specified. So far, only ctf iterator are supported.
41
42 >>> begin_pos = babeltrace.IterPos(babeltrace.SEEK_BEGIN)
43 >>> iterator = babeltrace.ctf.Iterator(ctx, begin_pos)
44
45 From there, it is possible to read the events.
46
47 >>> event = iterator.read_event()
48
49 It is simple to obtain the timestamp of that event.
50
51 >>> timestamp = event.get_timestamp()
52
53 Let's say that we want to extract the prev_comm context info for a
54 sched_switch event. To do so, it is needed to set an event scope
55 with which we can obtain the field wanted.
56
57 >>> if event.get_name == "sched_switch":
58 ... #prev_comm only for sched_switch events
59 ... scope = event.get_top_level_scope(babeltrace.ctf.scope.EVENT_FIELDS)
60 ... field = event.get_field(scope, "_prev_comm")
61 ... prev_comm = field.get_char_array()
62
63 It is also possible to move on to the next event.
64
65 >>> ret = iterator.next() # Move the iterator
66 >>> if ret == 0: # No error occured
67 ... event = iterator.read_event() # Read the next event
68
69 For many usage script examples of the Babeltrace Python module, see the
70 bindings/python/examples directory.
This page took 0.029642 seconds and 4 git commands to generate.