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

STREAMING
----------------

[Last updated: 2012-07-17 by David Goulet]

This is a brief howto for network streaming feature of lttng 2.0 toolchain.

See the README file for installation procedure or use the various Linux
distribution packages.

Terminology:

	* The "target" is the traced machine (either UST or/and kernel tracer)

	* The "remote" is the machine that receives the traces over network
	streaming transport layer.

Basics:

Here are the basic concepts of the new streaming component. We use two network
ports for that called _control_ and _data_ respectively defined by default to
5342 and 5343.

The control port is where the commands AND metadata data are sent since this
stream is considered to be the reliable and priority transport channel. The
data port is the stream which transports the tracing raw data.

In order to gather traces from the network, the remote machine MUST have a
lttng-relayd running on it bound to network interfaces remotely reachable by the
target.

[remote] $ lttng-relayd -d
(to daemonize)

[remote] $ lttng-relayd -vvv
(foreground with debug output)

[remote] $ lttng-relayd -C tcp://0.0.0.0:1234 -D tcp://0.0.0.0:5678
(control port set to TCP/1234 and data port to TCP/5678 on all IP addresses)

For now, only TCP is supported on IPv4/IPv6.

Once done, the following examples shows you how to start streaming from the
target machine to the remote host where we just started a lttng relay.

Example 1:
----------------

Simple and quick network streaming.

1) Create a tracing session that will be streamed over the network for the
specified domain. This session will contain, in our example, syscall events.

  # lttng create syscall-session

2) Enable the consumer to send data over the network for the kernel domain.

  # lttng enable-consumer --kernel net://<remote_addr>

  You can also skip this step and directly use the lttng create command like so:

  # lttng create -U net://<remote_addr> syscall-session

3) Set and start the tracing. Nothing new here.

  # lttng enable-event -a --syscall -k
  # lttng start
  (wait and get coffee)
  # lttng stop

By default on the relay side, the trace will be written to the lttng-traces/
directory of the relayd user in:

  hostname/session-name/kernel/*

The -o option of lttng-relayd allows the user to override the default output
path.

Just run babeltrace or lttng view -t PATH with the previous path.

Example 2:
----------------

This example uses all possible options to fine grained control the streaming.

1) Again, create a tracing session that will be streamed over the network for
the specified domain.

  # lttng create syscall-session

2) Set relayd URIs for the tracing session and kernel domain.

ONLY set the remote relayd URIs (both control and data at the same destination
and using default ports) on the consumer but does not enable the consumer to use
network streaming yet.

  # lttng enable-consumer -k -U net://<remote_addr>

You can also set both control and data URIs using -C and -D respectively for
that like so:

  # lttng enable-consumer -k -C tcp://<remote_addr> -D tcp://<remote_addr>

3) Enable the consumer previously setup with the relayd URIs.

This enables the previous network destination. From this point on, the consumer
is ready to stream once tracing is started.

  # lttng enable-consumer -k --enable

4) Set and start the tracing. Nothing new here.

  # lttng enable-event -a --syscall -k
  # lttng start
  (wait and get coffee)
  # lttng stop

Again, run babeltrace as mentioned in the previous example on the relayd side.

For more information, please read the --help options of each command or the man
pages lttng(1) and the lttng-relayd(8)
Commit	Line	Data
	1	STREAMING
	2	----------------
	3
	4	[Last updated: 2012-07-17 by David Goulet]
	5
	6	This is a brief howto for network streaming feature of lttng 2.0 toolchain.
	7
	8	See the README file for installation procedure or use the various Linux
	9	distribution packages.
	10
	11	Terminology:
	12
	13	* The "target" is the traced machine (either UST or/and kernel tracer)
	14
	15	* The "remote" is the machine that receives the traces over network
	16	streaming transport layer.
	17
	18	Basics:
	19
	20	Here are the basic concepts of the new streaming component. We use two network
	21	ports for that called _control_ and _data_ respectively defined by default to
	22	5342 and 5343.
	23
	24	The control port is where the commands AND metadata data are sent since this
	25	stream is considered to be the reliable and priority transport channel. The
	26	data port is the stream which transports the tracing raw data.
	27
	28	In order to gather traces from the network, the remote machine MUST have a
	29	lttng-relayd running on it bound to network interfaces remotely reachable by the
	30	target.
	31
	32	[remote] $ lttng-relayd -d
	33	(to daemonize)
	34
	35	[remote] $ lttng-relayd -vvv
	36	(foreground with debug output)
	37
	38	[remote] $ lttng-relayd -C tcp://0.0.0.0:1234 -D tcp://0.0.0.0:5678
	39	(control port set to TCP/1234 and data port to TCP/5678 on all IP addresses)
	40
	41	For now, only TCP is supported on IPv4/IPv6.
	42
	43	Once done, the following examples shows you how to start streaming from the
	44	target machine to the remote host where we just started a lttng relay.
	45
	46	Example 1:
	47	----------------
	48
	49	Simple and quick network streaming.
	50
	51	1) Create a tracing session that will be streamed over the network for the
	52	specified domain. This session will contain, in our example, syscall events.
	53
	54	# lttng create syscall-session
	55
	56	2) Enable the consumer to send data over the network for the kernel domain.
	57
	58	# lttng enable-consumer --kernel net://<remote_addr>
	59
	60	You can also skip this step and directly use the lttng create command like so:
	61
	62	# lttng create -U net://<remote_addr> syscall-session
	63
	64	3) Set and start the tracing. Nothing new here.
	65
	66	# lttng enable-event -a --syscall -k
	67	# lttng start
	68	(wait and get coffee)
	69	# lttng stop
	70
	71	By default on the relay side, the trace will be written to the lttng-traces/
	72	directory of the relayd user in:
	73
	74	hostname/session-name/kernel/*
	75
	76	The -o option of lttng-relayd allows the user to override the default output
	77	path.
	78
	79	Just run babeltrace or lttng view -t PATH with the previous path.
	80
	81	Example 2:
	82	----------------
	83
	84	This example uses all possible options to fine grained control the streaming.
	85
	86	1) Again, create a tracing session that will be streamed over the network for
	87	the specified domain.
	88
	89	# lttng create syscall-session
	90
	91	2) Set relayd URIs for the tracing session and kernel domain.
	92
	93	ONLY set the remote relayd URIs (both control and data at the same destination
	94	and using default ports) on the consumer but does not enable the consumer to use
	95	network streaming yet.
	96
	97	# lttng enable-consumer -k -U net://<remote_addr>
	98
	99	You can also set both control and data URIs using -C and -D respectively for
	100	that like so:
	101
	102	# lttng enable-consumer -k -C tcp://<remote_addr> -D tcp://<remote_addr>
	103
	104	3) Enable the consumer previously setup with the relayd URIs.
	105
	106	This enables the previous network destination. From this point on, the consumer
	107	is ready to stream once tracing is started.
	108
	109	# lttng enable-consumer -k --enable
	110
	111	4) Set and start the tracing. Nothing new here.
	112
	113	# lttng enable-event -a --syscall -k
	114	# lttng start
	115	(wait and get coffee)
	116	# lttng stop
	117
	118	Again, run babeltrace as mentioned in the previous example on the relayd side.
	119
	120	For more information, please read the --help options of each command or the man
	121	pages lttng(1) and the lttng-relayd(8)