Docs: update debuginfo doc
[babeltrace.git] / doc / python-howto.txt
CommitLineData
24a3136a
DS
1PYTHON BINDINGS
2----------------
3
4This is a brief howto for using the Babeltrace Python module.
5
6
7INSTALLATION:
8
94a6cea3
JG
9By default, the Python bindings are not generated.
10If you wish to generate and install the Python bindings, you can use the
11--enable-python-bindings configure option.
24a3136a 12
94a6cea3 13 $ ./configure --enable-python-bindings
24a3136a
DS
14
15The Python module is automatically generated using SWIG, therefore the
16swig2.0 package on Debian/Ubuntu is requied.
17
18
19USAGE:
20
21Once installed, the Python module can be used by importing it in Python.
22In the Python interpreter:
23
24 >>> import babeltrace
25
26Then 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
31Where <format> is a string containing the format name in which the trace
32was produced. To print a list of available formats to the standard
33output, 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
38When a trace is added to a context, it is opened and ready to read using
39an iterator. While creating an iterator, optional starting and ending
40position 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
45From there, it is possible to read the events.
46
47 >>> event = iterator.read_event()
48
49It is simple to obtain the timestamp of that event.
50
51 >>> timestamp = event.get_timestamp()
52
53Let's say that we want to extract the prev_comm context info for a
54sched_switch event. To do so, it is needed to set an event scope
55with 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
63It 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
69For many usage script examples of the Babeltrace Python module, see the
70bindings/python/examples directory.
This page took 0.024829 seconds and 4 git commands to generate.