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

lttng-untrack(1)
================
:revdate: 4 March 2020


NAME
----
lttng-untrack - Remove one or more values from an LTTng process attribute tracker


SYNOPSIS
--------
Remove specific process attribute values from a Linux kernel domain tracker:

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel
      (option:--pid=PID[,PID]... | option:--vpid=VPID[,VPID]... |
      option:--uid=UID[,UID]... | option:--vuid=VUID[,VUID]... |
      option:--gid=GID[,GID]... | option:--vgid=VGID[,VGID]... )...

Remove all possible process attribute values from a Linux kernel domain tracker:

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel
      option:--all (option:--pid | option:--vpid | option:--uid |
      option:--vuid | option:--gid | option:--vgid )...

Remove specific process attribute values from a user space domain tracker:

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace
      (option:--vpid=VPID[,VPID]... | option:--vuid=VUID[,VUID]... | option:--vgid=VGID[,VGID]...)...

Remove all possible process attribute values from a user space domain tracker:

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace
      option:--all (option:--vpid | option:--vgid | option:--vuid)...


DESCRIPTION
-----------
The `lttng untrack` commands removes one or more values from a
process attribute tracker.

See man:lttng-track(1) to learn more about LTTng trackers.

The untrack command removes specific process attribute values from a
tracker's inclusion set. The attributes to remove must have been
precedently added by man:lttng-track(1). It is also possible to remove
all the possible values of a process attribute from the inclusion set
using the option:--all option.


Example
~~~~~~~
One common operation is to create a tracing session
(see man:lttng-create(1)), remove all the entries from the PID
tracker inclusion set, start tracing, and then manually track PIDs
while tracing is active.

Assume the maximum system PID is 7 for this example.

Command:

[role="term"]
----
$ lttng create
----

Initial inclusion set:

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

Command:

[role="term"]
----
$ lttng untrack --kernel --pid --all
----

inclusion set:

-------------------------------
[ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
-------------------------------

Commands:

[role="term"]
----
$ lttng enable-event --kernel ...
$ lttng start
$ # ...
$ lttng track --kernel --pid=3,5
----

inclusion set:

-------------------------------
[ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
-------------------------------

Command:

[role="term"]
----
$ lttng track --kernel --pid=2
----

inclusion set:

-------------------------------
[ ] [ ] [2] [3] [ ] [5] [ ] [ ]
-------------------------------


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


Domain
~~~~~~
One of:

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

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


Target
~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
    Untrack process attributes in the tracing session named 'SESSION'
    instead of the current tracing session.


Untracking
~~~~~~~~~~
option:-a, option:--all::
    Used in conjunction with a single, empty option:--pid,
    option:--vpid, option:--uid, option:--vuid, option:--gid,
    or option:--vgid option: untrack _all_ possible process attribute
    values (remove all values from the inclusion set).

option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
    Untrack process ID values 'PID' (remove them from the process ID
    inclusion set).
+
'PID' is the process ID attribute of a process as seen from the _root
PID namespace_ (see man:pid_namespaces(7)). It can only be used with
the option:--kernel domain option.
+
The 'PID' argument must be omitted when also using the option:--all
option.

option:--vpid[='VPID'[,'VPID']...]::
    Untrack virtual process ID values 'VPID' (remove them from the
    virtual process ID inclusion set).
+
'VPID' is the virtual process ID attribute of a process as seen from
the _PID namespace_ of the process (see man:pid_namespaces(7)).
+
The 'VPID' argument must be omitted when also using the option:--all
option.

option:--uid[='USER'[,'USER']...]::
    Untrack user ID process attribute values 'USER' (remove them from
    the user ID inclusion set).
+
'USER' is the real user ID (see man:getuid(3)) of a process as seen
from the _root user namespace_ (see man:user_namespaces(7)). It can
only be used with the option:--kernel domain option.
+
'USER' can also be a user name. No name resolution is performed;
'USER' will be matched against the names in the inclusion set.
+
The 'USER' argument must be omitted when also using the option:--all
option.

option:--vuid[='USER'[,'USER']...]::
    Untrack virtual user ID process attribute values 'USER' (remove
    them from the virtual user ID inclusion set).
+
'USER' is the real user ID (see man:getuid(3)) of a process as seen
from the _user namespace_ of the process (see man:user_namespaces(7)).
+
'USER' can also be a user name. No name resolution is performed;
'USER' will be matched against the names in the inclusion set.
+
The 'USER' argument must be omitted when also using the option:--all
option.

option:--gid[='GROUP'[,'GROUP']...]::
    Untrack group ID process attribute values 'GROUP' (remove them
    from the group ID inclusion set).
+
'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
from the _root user namespace_ (see man:user_namespaces(7)). It can
only be used with the option:--kernel domain option.
+
'GROUP' can also be a group name. No name resolution is performed;
'GROUP' will be matched against the names in the inclusion set.
+
The 'GROUP' argument must be omitted when also using the option:--all
option.

option:--vgid[='GROUP'[,'GROUP']...]::
    Untrack virtual group ID process attribute values 'GROUP'(remove
    them from the virtual group ID inclusion set).
+
'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
from the _user namespace_ of the process (see man:user_namespaces(7)).
+
'GROUP' can also be a group name. No name resolution is performed;
'GROUP' will be matched against the names in the inclusion set.
+
The 'GROUP' 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-track(1),
man:lttng(1)
Commit	Line	Data
	1	lttng-untrack(1)
	2	================
	3	:revdate: 4 March 2020
	4
	5
	6	NAME
	7	----
	8	lttng-untrack - Remove one or more values from an LTTng process attribute tracker
	9
	10
	11	SYNOPSIS
	12	--------
	13	Remove specific process attribute values from a Linux kernel domain tracker:
	14
	15	[verse]
	16	lttng ['linkgenoptions:(GENERAL OPTIONS)'] untrack option:--kernel
	17	(option:--pid=PID[,PID]... \| option:--vpid=VPID[,VPID]... \|
	18	option:--uid=UID[,UID]... \| option:--vuid=VUID[,VUID]... \|
	19	option:--gid=GID[,GID]... \| option:--vgid=VGID[,VGID]... )...
	20
	21	Remove all possible process attribute values from a Linux kernel domain tracker:
	22
	23	[verse]
	24	lttng ['linkgenoptions:(GENERAL OPTIONS)'] untrack option:--kernel
	25	option:--all (option:--pid \| option:--vpid \| option:--uid \|
	26	option:--vuid \| option:--gid \| option:--vgid )...
	27
	28	Remove specific process attribute values from a user space domain tracker:
	29
	30	[verse]
	31	lttng ['linkgenoptions:(GENERAL OPTIONS)'] untrack option:--userspace
	32	(option:--vpid=VPID[,VPID]... \| option:--vuid=VUID[,VUID]... \| option:--vgid=VGID[,VGID]...)...
	33
	34	Remove all possible process attribute values from a user space domain tracker:
	35
	36	[verse]
	37	lttng ['linkgenoptions:(GENERAL OPTIONS)'] untrack option:--userspace
	38	option:--all (option:--vpid \| option:--vgid \| option:--vuid)...
	39
	40
	41	DESCRIPTION
	42	-----------
	43	The `lttng untrack` commands removes one or more values from a
	44	process attribute tracker.
	45
	46	See man:lttng-track(1) to learn more about LTTng trackers.
	47
	48	The untrack command removes specific process attribute values from a
	49	tracker's inclusion set. The attributes to remove must have been
	50	precedently added by man:lttng-track(1). It is also possible to remove
	51	all the possible values of a process attribute from the inclusion set
	52	using the option:--all option.
	53
	54
	55	Example
	56	~~~~~~~
	57	One common operation is to create a tracing session
	58	(see man:lttng-create(1)), remove all the entries from the PID
	59	tracker inclusion set, start tracing, and then manually track PIDs
	60	while tracing is active.
	61
	62	Assume the maximum system PID is 7 for this example.
	63
	64	Command:
	65
	66	[role="term"]
	67	----
	68	$ lttng create
	69	----
	70
	71	Initial inclusion set:
	72
	73	-------------------------------
	74	[0] [1] [2] [3] [4] [5] [6] [7]
	75	-------------------------------
	76
	77	Command:
	78
	79	[role="term"]
	80	----
	81	$ lttng untrack --kernel --pid --all
	82	----
	83
	84	inclusion set:
	85
	86	-------------------------------
	87	[ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
	88	-------------------------------
	89
	90	Commands:
	91
	92	[role="term"]
	93	----
	94	$ lttng enable-event --kernel ...
	95	$ lttng start
	96	$ # ...
	97	$ lttng track --kernel --pid=3,5
	98	----
	99
	100	inclusion set:
	101
	102	-------------------------------
	103	[ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
	104	-------------------------------
	105
	106	Command:
	107
	108	[role="term"]
	109	----
	110	$ lttng track --kernel --pid=2
	111	----
	112
	113	inclusion set:
	114
	115	-------------------------------
	116	[ ] [ ] [2] [3] [ ] [5] [ ] [ ]
	117	-------------------------------
	118
	119
	120	include::common-cmd-options-head.txt[]
	121
	122
	123	Domain
	124	~~~~~~
	125	One of:
	126
	127	option:-k, option:--kernel::
	128	Track process attributes in the Linux kernel domain.
	129
	130	option:-u, option:--userspace::
	131	Track process attributes in the user space domain.
	132
	133
	134	Target
	135	~~~~~~
	136	option:-s 'SESSION', option:--session='SESSION'::
	137	Untrack process attributes in the tracing session named 'SESSION'
	138	instead of the current tracing session.
	139
	140
	141	Untracking
	142	~~~~~~~~~~
	143	option:-a, option:--all::
	144	Used in conjunction with a single, empty option:--pid,
	145	option:--vpid, option:--uid, option:--vuid, option:--gid,
	146	or option:--vgid option: untrack _all_ possible process attribute
	147	values (remove all values from the inclusion set).
	148
	149	option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
	150	Untrack process ID values 'PID' (remove them from the process ID
	151	inclusion set).
	152	+
	153	'PID' is the process ID attribute of a process as seen from the _root
	154	PID namespace_ (see man:pid_namespaces(7)). It can only be used with
	155	the option:--kernel domain option.
	156	+
	157	The 'PID' argument must be omitted when also using the option:--all
	158	option.
	159
	160	option:--vpid[='VPID'[,'VPID']...]::
	161	Untrack virtual process ID values 'VPID' (remove them from the
	162	virtual process ID inclusion set).
	163	+
	164	'VPID' is the virtual process ID attribute of a process as seen from
	165	the _PID namespace_ of the process (see man:pid_namespaces(7)).
	166	+
	167	The 'VPID' argument must be omitted when also using the option:--all
	168	option.
	169
	170	option:--uid[='USER'[,'USER']...]::
	171	Untrack user ID process attribute values 'USER' (remove them from
	172	the user ID inclusion set).
	173	+
	174	'USER' is the real user ID (see man:getuid(3)) of a process as seen
	175	from the _root user namespace_ (see man:user_namespaces(7)). It can
	176	only be used with the option:--kernel domain option.
	177	+
	178	'USER' can also be a user name. No name resolution is performed;
	179	'USER' will be matched against the names in the inclusion set.
	180	+
	181	The 'USER' argument must be omitted when also using the option:--all
	182	option.
	183
	184	option:--vuid[='USER'[,'USER']...]::
	185	Untrack virtual user ID process attribute values 'USER' (remove
	186	them from the virtual user ID inclusion set).
	187	+
	188	'USER' is the real user ID (see man:getuid(3)) of a process as seen
	189	from the _user namespace_ of the process (see man:user_namespaces(7)).
	190	+
	191	'USER' can also be a user name. No name resolution is performed;
	192	'USER' will be matched against the names in the inclusion set.
	193	+
	194	The 'USER' argument must be omitted when also using the option:--all
	195	option.
	196
	197	option:--gid[='GROUP'[,'GROUP']...]::
	198	Untrack group ID process attribute values 'GROUP' (remove them
	199	from the group ID inclusion set).
	200	+
	201	'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
	202	from the _root user namespace_ (see man:user_namespaces(7)). It can
	203	only be used with the option:--kernel domain option.
	204	+
	205	'GROUP' can also be a group name. No name resolution is performed;
	206	'GROUP' will be matched against the names in the inclusion set.
	207	+
	208	The 'GROUP' argument must be omitted when also using the option:--all
	209	option.
	210
	211	option:--vgid[='GROUP'[,'GROUP']...]::
	212	Untrack virtual group ID process attribute values 'GROUP'(remove
	213	them from the virtual group ID inclusion set).
	214	+
	215	'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
	216	from the _user namespace_ of the process (see man:user_namespaces(7)).
	217	+
	218	'GROUP' can also be a group name. No name resolution is performed;
	219	'GROUP' will be matched against the names in the inclusion set.
	220	+
	221	The 'GROUP' argument must be omitted when also using the option:--all
	222	option.
	223
	224
	225	include::common-cmd-help-options.txt[]
	226
	227
	228	include::common-cmd-footer.txt[]
	229
	230
	231	SEE ALSO
	232	--------
	233	man:lttng-track(1),
	234	man:lttng(1)