[babeltrace.git] / doc / python-howto.txt

PYTHON BINDINGS
----------------

This is a brief howto for using the Babeltrace Python module.


INSTALLATION:

By default, the Python bindings are not generated.
If you wish to generate and install the Python bindings, you can use the
--enable-python-bindings configure option.

  $ ./configure --enable-python-bindings

The Python module is automatically generated using SWIG, therefore the
swig2.0 package on Debian/Ubuntu is requied.


USAGE:

Once installed, the Python module can be used by importing it in Python.
In the Python interpreter:

  >>> import babeltrace

Then the starting point is to create a context and add a trace to it.

  >>> ctx = babeltrace.Context()
  >>> ctx.add_trace("path/to/trace", <format>)

Where <format> is a string containing the format name in which the trace
was produced.  To print a list of available formats to the standard
output, it is possible to use the print_format_list function.

  >>> out = babeltrace.File(None)	# This returns stdout
  >>> babeltrace.print_format_list(out)

When a trace is added to a context, it is opened and ready to read using
an iterator.  While creating an iterator, optional starting and ending
position may be specified.  So far, only ctf iterator are supported.

  >>> begin_pos = babeltrace.IterPos(babeltrace.SEEK_BEGIN)
  >>> iterator = babeltrace.ctf.Iterator(ctx, begin_pos)

From there, it is possible to read the events.

  >>> event = iterator.read_event()

It is simple to obtain the timestamp of that event.

  >>> timestamp = event.get_timestamp()

Let's say that we want to extract the prev_comm context info for a
sched_switch event.  To do so, it is needed to set an event scope
with which we can obtain the field wanted.

  >>> if event.get_name == "sched_switch":
  ...   #prev_comm only for sched_switch events
  ...   scope = event.get_top_level_scope(babeltrace.ctf.scope.EVENT_FIELDS)
  ...   field = event.get_field(scope, "_prev_comm")
  ...   prev_comm = field.get_char_array()

It is also possible to move on to the next event.

  >>> ret = iterator.next()		# Move the iterator
  >>> if ret == 0:			# No error occured
  ...   event = iterator.read_event()	# Read the next event

For many usage script examples of the Babeltrace Python module, see the
bindings/python/examples directory.
Commit	Line	Data
	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.