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.