lttng-untrack(1)
================
+:revdate: 14 June 2021
NAME
----
-lttng-untrack - Remove one or more entries from an LTTng resource tracker
+lttng-untrack - Disallow specific processes to record LTTng events
SYNOPSIS
--------
+Disallow specific processes to record Linux kernel events:
+
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel [option:--session='SESSION']
+ (option:--pid=PID[,PID]... | option:--vpid=VPID[,VPID]... |
+ option:--uid=UID[,UID]... | option:--vuid=VUSER[,VUSER]... |
+ option:--gid=GID[,GID]... | option:--vgid=VGROUP[,VGROUP]...)...
+
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel [option:--session='SESSION']
+ option:--all (option:--pid | option:--vpid | option:--uid | option:--vuid | option:--gid | option:--vgid)...
+
+Disallow specific processes to record user space events:
+
[verse]
-*lttng* ['GENERAL OPTIONS'] *untrack* (option:--kernel | option:--userspace)
- [option:--session='SESSION'] (option:--pid='PID'[,'PID']... | option:--all option:--pid)
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace [option:--session='SESSION']
+ (option:--vpid=VPID[,VPID]... | option:--vuid=VUSER[,VUSER]... |
+ option:--vgid=VGROUP[,VGROUP]...)...
+
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace [option:--session='SESSION']
+ option:--all (option:--vpid | option:--vgid | option:--vuid)...
DESCRIPTION
-----------
-The `lttng untrack` commands removes one or more entries from a
-resource tracker.
-
-See linklttng:lttng-track(1) to learn more about LTTng trackers.
+The `lttng untrack` command disallows one or more processes to record
+LTTng events based on their attributes within:
-The untrack command removes specific resources from a tracker. The
-resources to remove must have been precedently added by
-linklttng:lttng-track(1). It is also possible to remove all the
-resources from the whitelist using the option:--all option.
+With the option:--session='SESSION' option::
+ The recording session named 'SESSION'.
-As of this version, the only available tracker is the PID tracker.
+Without the option:--session option::
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
+See man:lttng-concepts(7) to learn more about recording sessions and
+recording event rules.
-Example
-~~~~~~~
-One common operation is to create a tracing session
-(see linklttng:lttng-create(1)), remove all the entries from the PID
-tracker whitelist, start tracing, and then manually track PIDs
-while tracing is active.
+The `untrack` command removes values from _inclusion sets_ of process
+attributes. See man:lttng-track(1) to learn more about inclusion sets.
-Assume the maximum system PID is 7 for this example.
+See the ``<<examples,EXAMPLES>>'' section below for usage examples.
-Command:
-[role="term"]
-------------
-lttng create
-------------
+Inclusion set example
+~~~~~~~~~~~~~~~~~~~~~
+A common operation is to create a recording session (see
+man:lttng-create(1)), remove all the entries from the Linux kernel
+process ID inclusion set, start recording, and then manually add PIDs
+while the recording session is active.
-Initial whitelist:
+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:
-
+. Command:
++
[role="term"]
--------------------------------------
-lttng untrack --userspace --pid --all
--------------------------------------
-
-Whitelist:
-
+----
+$ lttng untrack --kernel --all --pid
+----
++
+Inclusion set:
++
-------------------------------
[ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
-------------------------------
-Commands:
-
+. Commands:
++
[role="term"]
-----------------------------------
-lttng enable-event --userspace ...
-lttng start
-# ...
-lttng track --userspace --pid=3,5
-----------------------------------
-
-Whitelist:
-
+----
+$ lttng enable-event --kernel ...
+$ lttng start
+$ # ...
+$ lttng track --kernel --pid=3,5
+----
++
+Inclusion set:
++
-------------------------------
[ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
-------------------------------
-Command:
-
+. Command:
++
[role="term"]
--------------------------------
-lttng track --userspace --pid=2
--------------------------------
-
-Whitelist:
-
+----
+$ lttng track --kernel --pid=2
+----
++
+Inclusion set:
++
-------------------------------
[ ] [ ] [2] [3] [ ] [5] [ ] [ ]
-------------------------------
-include::common-cmd-options-head.txt[]
+include::common-lttng-cmd-options-head.txt[]
-Domain
-~~~~~~
+Tracing domain
+~~~~~~~~~~~~~~
One of:
option:-k, option:--kernel::
- Untrack resources tracked in the Linux kernel domain.
+ Remove values from one or more Linux kernel inclusion sets.
option:-u, option:--userspace::
- Untrack resources tracked in the user space domain.
+ Remove values from one or more user space inclusion sets.
-Target
-~~~~~~
-option:-s, option:--session='SESSION'::
- Untrack resources in the tracing session named 'SESSION' instead of
- the current tracing session.
+Recording target
+~~~~~~~~~~~~~~~~
+option:-s 'SESSION', option:--session='SESSION'::
+ Remove values from one or more inclusion sets of the recording
+ session named 'SESSION' instead of the current recording session.
-Untracking
-~~~~~~~~~~
-option:-a, option:--all::
- Used in conjunction with an empty option:--pid option: untrack _all_
- process IDs (clear the whitelist).
+Inclusion set selection
+~~~~~~~~~~~~~~~~~~~~~~~
+option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
+ For each 'PID' argument, remove 'PID' from the process ID inclusion
+ set of the selected recording session and domain.
++
+'PID' is the process ID attribute of a process as seen from the root
+PID namespace (see man:pid_namespaces(7)).
++
+Only available with option:--kernel option.
+
+option:--vpid[='VPID'[,'VPID']...]::
+ For each 'VPID' argument, remove 'VPID' from the virtual process ID
+ inclusion set of the selected recording session and domain.
++
+'VPID' is the virtual process ID attribute of a process as seen from
+the PID namespace of the process (see man:pid_namespaces(7)).
+
+option:--uid[='USER'[,'USER']...]::
+ For each 'USER' argument, remove 'USER' from the user ID inclusion
+ set of the selected recording session and domain.
++
+'USER' is either:
++
+--
+* The real user ID (see man:getuid(3)) of a process as seen
+ from the root user namespace (see man:user_namespaces(7)).
+
+* A user name.
++
+The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
+the user name resolution on removal from the user ID inclusion set.
+--
++
+Only available with option:--kernel option.
+
+option:--vuid[='VUSER'[,'VUSER']...]::
+ For each 'VUSER' argument, remove 'VUSER' from the virtual user ID
+ inclusion set of the selected recording session and domain.
++
+'VUSER' is either:
++
+--
+* The real user ID (see man:getuid(3)) of a process as seen
+ from the user namespace (see man:user_namespaces(7)).
+
+* A user name.
++
+The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
+the user name resolution on removal from the virtual user ID inclusion
+set.
+--
+
+option:--gid[='GROUP'[,'GROUP']...]::
+ For each 'GROUP' argument, remove 'GROUP' from the group ID
+ inclusion set of the selected recording session and domain.
++
+'GROUP' is either:
++
+--
+* The real group ID (see man:getgid(3)) of a process as seen from the
+ root user namespace (see man:user_namespaces(7)).
+
+* A group name.
++
+The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
+the group name resolution on removal from the group ID inclusion set.
+--
++
+Only available with option:--kernel option.
+
+option:--vgid[='VGROUP'[,'VGROUP']...]::
+ For each 'VGROUP' argument, remove 'VGROUP' from the virtual group
+ ID inclusion set of the selected recording session and domain.
++
+'VGROUP' is either:
++
+--
+* The real group ID (see man:getgid(3)) of a process as seen
+ from the user namespace (see man:user_namespaces(7)).
-option:-p, option:--pid[='PID'[,'PID']...]::
- Untrack process IDs 'PID' (remove them from the current whitelist).
+* A group name.
+
-The 'PID' argument must be omitted when also using the option:--all
-option.
+The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
+the group name resolution on removal from the virtual group ID inclusion
+set.
+--
-include::common-cmd-help-options.txt[]
+Inclusion set operation
+~~~~~~~~~~~~~~~~~~~~~~~
+option:-a, option:--all::
+ With one or more empty option:--pid, option:--vpid, option:--uid,
+ option:--vuid, option:--gid, and option:--vgid options: clear the
+ selected inclusion sets.
+
+
+include::common-lttng-cmd-help-options.txt[]
+
+
+include::common-lttng-cmd-after-options.txt[]
+
+
+[[examples]]
+EXAMPLES
+--------
+.Remove the PIDs 1728 and 3775 from the Linux kernel process ID inclusion set of the current recording session.
+====
+See the option:--pid option.
+
+[role="term"]
+----
+$ lttng untrack --kernel --pid=1728,3775
+----
+====
+
+.Remove the IDs of a specific groups from the user space virtual group ID inclusion set of a specific recording session.
+====
+See the option:--vgid and option:--session options.
+
+[role="term"]
+----
+$ lttng untrack --userspace --session=my-session \
+ --vgid=docker,mysql
+----
+====
+
+.Remove all the user IDs from the Linux kernel user ID inclusion set of the current recording session.
+====
+See the option:--all and option:--uid options.
+
+[role="term"]
+----
+$ lttng untrack --kernel --all --uid
+----
+====
-include::common-cmd-footer.txt[]
+include::common-footer.txt[]
SEE ALSO
--------
-linklttng:lttng-track(1),
-linklttng:lttng(1)
+man:lttng(1),
+man:lttng-track(1),
+man:lttng-concepts(7)
projects / lttng-tools.git / blobdiff