[lttng-tools.git] / doc / man / lttng-track.1.txt

lttng-track(1)
==============
:revdate: 14 March 2017


NAME
----
lttng-track - Add one or more entries to an LTTng resource tracker


SYNOPSIS
--------
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* (option:--kernel | option:--userspace)
      [option:--session='SESSION'] (option:--pid='PID'[,'PID']... | option:--all option:--pid)


DESCRIPTION
-----------
The `lttng track` commands adds one or more entries to a
resource tracker.

A resource tracker is a _whitelist_ of resources. Tracked resources are
allowed to emit events, provided those events are targeted by enabled
event rules (see man:lttng-enable-event(1)).

Tracker entries can be removed from the whitelist with
man:lttng-untrack(1).

As of this version, the only available tracker is the *PID tracker*. The
process ID (PID) tracker follows one or more process IDs; only the
processes with a tracked PID are allowed to emit events. By default, all
possible PIDs on the system are tracked: any process may emit enabled
events (equivalent of `lttng track --pid --all` for all domains).

With the PID tracker, it is possible, for example, to record all system
calls called by a given process:

[role="term"]
----
# lttng enable-event --kernel --all --syscall
# lttng track --kernel --pid=2345
# lttng start
----

If all the PIDs are tracked (i.e. `lttng track --pid --all`, which is
the default state of all domains when creating a tracing session), then
using the track command with one or more specific PIDs has the effect of
first removing all the PIDs from the whitelist, then adding the
specified PIDs.


Example
~~~~~~~
Assume the maximum system PID is 7 for this example.

Initial whitelist:

-------------------------------
[0] [1] [2] [3] [4] [5] [6] [7]
-------------------------------

Command:

[role="term"]
----
$ lttng track --userspace --pid=3,6,7
----

Whitelist:

-------------------------------
[ ] [ ] [ ] [3] [ ] [ ] [6] [7]
-------------------------------

Command:

[role="term"]
----
$ lttng untrack --userspace --pid=7
----

Whitelist:

-------------------------------
[ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
-------------------------------

Command:

[role="term"]
----
$ lttng track --userspace --pid=1,5
----

Whitelist:

-------------------------------
[ ] [1] [ ] [3] [ ] [5] [6] [ ]
-------------------------------

It should be noted that the PID tracker tracks the numeric process IDs.
Should a process with a given ID exit and another process be given this
ID, then the latter would also be allowed to emit events.

See the man:lttng-untrack(1) for more details about removing
entries.


include::common-cmd-options-head.txt[]


Domain
~~~~~~
One of:

option:-k, option:--kernel::
    Track resources in the Linux kernel domain.

option:-u, option:--userspace::
    Track resources in the user space domain.


Target
~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
    Track resources in the tracing session named 'SESSION' instead of
    the current tracing session.


Tracking
~~~~~~~~
option:-a, option:--all::
    Used in conjunction with an empty option:--pid option: track _all_
    process IDs (add all entries to the whitelist).

option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
    Track process IDs 'PID' (add them to the current whitelist).
+
The 'PID' argument must be omitted when also using the option:--all
option.


include::common-cmd-help-options.txt[]


include::common-cmd-footer.txt[]


SEE ALSO
--------
man:lttng-untrack(1),
man:lttng(1)
Commit	Line	Data
	1	lttng-track(1)
	2	==============
	3	:revdate: 14 March 2017
	4
	5
	6	NAME
	7	----
	8	lttng-track - Add one or more entries to an LTTng resource tracker
	9
	10
	11	SYNOPSIS
	12	--------
	13	[verse]
	14	lttng ['linkgenoptions:(GENERAL OPTIONS)'] track (option:--kernel \| option:--userspace)
	15	[option:--session='SESSION'] (option:--pid='PID'[,'PID']... \| option:--all option:--pid)
	16
	17
	18	DESCRIPTION
	19	-----------
	20	The `lttng track` commands adds one or more entries to a
	21	resource tracker.
	22
	23	A resource tracker is a _whitelist_ of resources. Tracked resources are
	24	allowed to emit events, provided those events are targeted by enabled
	25	event rules (see man:lttng-enable-event(1)).
	26
	27	Tracker entries can be removed from the whitelist with
	28	man:lttng-untrack(1).
	29
	30	As of this version, the only available tracker is the PID tracker. The
	31	process ID (PID) tracker follows one or more process IDs; only the
	32	processes with a tracked PID are allowed to emit events. By default, all
	33	possible PIDs on the system are tracked: any process may emit enabled
	34	events (equivalent of `lttng track --pid --all` for all domains).
	35
	36	With the PID tracker, it is possible, for example, to record all system
	37	calls called by a given process:
	38
	39	[role="term"]
	40	----
	41	# lttng enable-event --kernel --all --syscall
	42	# lttng track --kernel --pid=2345
	43	# lttng start
	44	----
	45
	46	If all the PIDs are tracked (i.e. `lttng track --pid --all`, which is
	47	the default state of all domains when creating a tracing session), then
	48	using the track command with one or more specific PIDs has the effect of
	49	first removing all the PIDs from the whitelist, then adding the
	50	specified PIDs.
	51
	52
	53	Example
	54	~~~~~~~
	55	Assume the maximum system PID is 7 for this example.
	56
	57	Initial whitelist:
	58
	59	-------------------------------
	60	[0] [1] [2] [3] [4] [5] [6] [7]
	61	-------------------------------
	62
	63	Command:
	64
	65	[role="term"]
	66	----
	67	$ lttng track --userspace --pid=3,6,7
	68	----
	69
	70	Whitelist:
	71
	72	-------------------------------
	73	[ ] [ ] [ ] [3] [ ] [ ] [6] [7]
	74	-------------------------------
	75
	76	Command:
	77
	78	[role="term"]
	79	----
	80	$ lttng untrack --userspace --pid=7
	81	----
	82
	83	Whitelist:
	84
	85	-------------------------------
	86	[ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
	87	-------------------------------
	88
	89	Command:
	90
	91	[role="term"]
	92	----
	93	$ lttng track --userspace --pid=1,5
	94	----
	95
	96	Whitelist:
	97
	98	-------------------------------
	99	[ ] [1] [ ] [3] [ ] [5] [6] [ ]
	100	-------------------------------
	101
	102	It should be noted that the PID tracker tracks the numeric process IDs.
	103	Should a process with a given ID exit and another process be given this
	104	ID, then the latter would also be allowed to emit events.
	105
	106	See the man:lttng-untrack(1) for more details about removing
	107	entries.
	108
	109
	110	include::common-cmd-options-head.txt[]
	111
	112
	113	Domain
	114	~~~~~~
	115	One of:
	116
	117	option:-k, option:--kernel::
	118	Track resources in the Linux kernel domain.
	119
	120	option:-u, option:--userspace::
	121	Track resources in the user space domain.
	122
	123
	124	Target
	125	~~~~~~
	126	option:-s 'SESSION', option:--session='SESSION'::
	127	Track resources in the tracing session named 'SESSION' instead of
	128	the current tracing session.
	129
	130
	131	Tracking
	132	~~~~~~~~
	133	option:-a, option:--all::
	134	Used in conjunction with an empty option:--pid option: track _all_
	135	process IDs (add all entries to the whitelist).
	136
	137	option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
	138	Track process IDs 'PID' (add them to the current whitelist).
	139	+
	140	The 'PID' argument must be omitted when also using the option:--all
	141	option.
	142
	143
	144	include::common-cmd-help-options.txt[]
	145
	146
	147	include::common-cmd-footer.txt[]
	148
	149
	150	SEE ALSO
	151	--------
	152	man:lttng-untrack(1),
	153	man:lttng(1)