X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng-untrack.1.txt;h=f1a8720249f50daf2669602375129064bcf32cd7;hp=43d135c63aa94676743c6ae49523bc03089661f6;hb=de3323397026157322a512b6755792fe153ad17f;hpb=7c1a4458be934fec31aa27a0eb52e4d0b8cb3803 diff --git a/doc/man/lttng-untrack.1.txt b/doc/man/lttng-untrack.1.txt index 43d135c63..f1a872024 100644 --- a/doc/man/lttng-untrack.1.txt +++ b/doc/man/lttng-untrack.1.txt @@ -1,39 +1,62 @@ lttng-untrack(1) ================ +:revdate: 4 March 2020 NAME ---- -lttng-untrack - Remove one or more entries from an LTTng resource tracker +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:--kernel | option:--userspace) - [option:--session='SESSION'] (option:--pid='PID'[,'PID']... | option:--all option:--pid) +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace + option:--all (option:--vpid | option:--vgid | option:--vuid)... DESCRIPTION ----------- -The `lttng untrack` commands removes one or more entries from a -resource tracker. +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 resources from a tracker. The -resources to remove must have been precedently added by -man:lttng-track(1). It is also possible to remove all the -resources from the whitelist using the option:--all option. - -As of this version, the only available tracker is the PID tracker. +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 whitelist, start tracing, and then manually track PIDs +tracker inclusion set, start tracing, and then manually track PIDs while tracing is active. Assume the maximum system PID is 7 for this example. @@ -41,11 +64,11 @@ Assume the maximum system PID is 7 for this example. Command: [role="term"] ------------- -lttng create ------------- +---- +$ lttng create +---- -Initial whitelist: +Initial inclusion set: ------------------------------- [0] [1] [2] [3] [4] [5] [6] [7] @@ -54,11 +77,11 @@ Initial whitelist: Command: [role="term"] -------------------------------------- -lttng untrack --userspace --pid --all -------------------------------------- +---- +$ lttng untrack --kernel --pid --all +---- -Whitelist: +inclusion set: ------------------------------- [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] @@ -67,14 +90,14 @@ Whitelist: Commands: [role="term"] ----------------------------------- -lttng enable-event --userspace ... -lttng start -# ... -lttng track --userspace --pid=3,5 ----------------------------------- +---- +$ lttng enable-event --kernel ... +$ lttng start +$ # ... +$ lttng track --kernel --pid=3,5 +---- -Whitelist: +inclusion set: ------------------------------- [ ] [ ] [ ] [3] [ ] [5] [ ] [ ] @@ -83,11 +106,11 @@ Whitelist: Command: [role="term"] -------------------------------- -lttng track --userspace --pid=2 -------------------------------- +---- +$ lttng track --kernel --pid=2 +---- -Whitelist: +inclusion set: ------------------------------- [ ] [ ] [2] [3] [ ] [5] [ ] [ ] @@ -102,31 +125,102 @@ Domain One of: option:-k, option:--kernel:: - Untrack resources tracked in the Linux kernel domain. + Track process attributes in the Linux kernel domain. option:-u, option:--userspace:: - Untrack resources tracked in the user space domain. + Track process attributes in the user space domain. Target ~~~~~~ -option:-s, option:--session='SESSION':: - Untrack resources in the tracing session named 'SESSION' instead of - the current tracing session. +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 an empty option:--pid option: untrack _all_ - process IDs (clear the whitelist). - -option:-p, option:--pid[='PID'[,'PID']...]:: - Untrack process IDs 'PID' (remove them from the current whitelist). + 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[]