X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng-untrack.1.txt;h=9a485950c414b154927728a85beedfd3718fd702;hp=b7da339df9c06b2204d0d23b3ed6a8bc9428bf67;hb=e971184584781f70bbbfc52bbede8b9abf0436e5;hpb=ce19b9ed9bd9591bd0c4d1998780082a490991fd diff --git a/doc/man/lttng-untrack.1.txt b/doc/man/lttng-untrack.1.txt index b7da339df..9a485950c 100644 --- a/doc/man/lttng-untrack.1.txt +++ b/doc/man/lttng-untrack.1.txt @@ -1,140 +1,289 @@ 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* ['linkgenoptions:(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 ``<>'' 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)