[lttng-tools.git] / doc / python-howto.txt

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

This is a brief howto for using the lttng-tools Python module.

By default, the Python bindings are not installed.
If you wish the Python bindings, you can configure with the
--enable-python-bindings option during the installation procedure:

  $ ./configure --enable-python-bindings

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

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

  >>> import lttng

Example:
----------------

Quick example using Python to trace with LTTng.

1) Run python

  $ python

2) Import the lttng module

  >>> import lttng

3) Create a session

  >>> lttng.create("session-name", "path/to/trace")

4) Create a handle for the tracing session and domain

  >>> domain = lttng.Domain()
  >>> domain.type = lttng.DOMAIN_KERNEL			*
  >>> handle = lttng.Handle("session-name", domain)

* This line is somewhat useless since domain.type is set to 0
  by default, the corresponding value of lttng.DOMAIN_KERNEL

5) Enable all Kernel events

  >>> event = lttng.Event()
  >>> event.type = lttng.EVENT_TRACEPOINT		*
  >>> event.loglevel_type = lttng.EVENT_LOGLEVEL_ALL	*
  >>> lttng.enable_event(handle, event, None)

* These two lines are somewhat useless since event.type
  and event.loglevel_type are by default set to 0, the
  corresponding value of lttng.EVENT_TRACEPOINT and
  lttng.EVENT_LOGLEVEL_ALL

5) Start tracing

  >>> lttng.start("session-name")

6) Stop tracing

  >>> lttng.stop("session-name")

7) Destroy the tracing session

  >>> lttng.destroy("session-name")

For an example script with more details, see extras/bindings/swig/python/tests/example.py
Commit	Line	Data
	1	PYTHON BINDINGS
	2	----------------
	3
	4	This is a brief howto for using the lttng-tools Python module.
	5
	6	By default, the Python bindings are not installed.
	7	If you wish the Python bindings, you can configure with the
	8	--enable-python-bindings option during the installation procedure:
	9
	10	$ ./configure --enable-python-bindings
	11
	12	The Python module is automatically generated using SWIG, therefore the
	13	swig2.0 package on Debian/Ubuntu is requied.
	14
	15	Once installed, the Python module can be used by importing it in Python.
	16	In the Python interpreter:
	17
	18	>>> import lttng
	19
	20	Example:
	21	----------------
	22
	23	Quick example using Python to trace with LTTng.
	24
	25	1) Run python
	26
	27	$ python
	28
	29	2) Import the lttng module
	30
	31	>>> import lttng
	32
	33	3) Create a session
	34
	35	>>> lttng.create("session-name", "path/to/trace")
	36
	37	4) Create a handle for the tracing session and domain
	38
	39	>>> domain = lttng.Domain()
	40	>>> domain.type = lttng.DOMAIN_KERNEL *
	41	>>> handle = lttng.Handle("session-name", domain)
	42
	43	* This line is somewhat useless since domain.type is set to 0
	44	by default, the corresponding value of lttng.DOMAIN_KERNEL
	45
	46	5) Enable all Kernel events
	47
	48	>>> event = lttng.Event()
	49	>>> event.type = lttng.EVENT_TRACEPOINT *
	50	>>> event.loglevel_type = lttng.EVENT_LOGLEVEL_ALL *
	51	>>> lttng.enable_event(handle, event, None)
	52
	53	* These two lines are somewhat useless since event.type
	54	and event.loglevel_type are by default set to 0, the
	55	corresponding value of lttng.EVENT_TRACEPOINT and
	56	lttng.EVENT_LOGLEVEL_ALL
	57
	58	5) Start tracing
	59
	60	>>> lttng.start("session-name")
	61
	62	6) Stop tracing
	63
	64	>>> lttng.stop("session-name")
	65
	66	7) Destroy the tracing session
	67
	68	>>> lttng.destroy("session-name")
	69
	70	For an example script with more details, see extras/bindings/swig/python/tests/example.py