X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng-track.1.txt;h=fd854c03c030bd0940eeefe3b0f1e1928fbe70c3;hp=646b55cad5fb6a93d7c4df903a59fcdbf79af116;hb=e971184584781f70bbbfc52bbede8b9abf0436e5;hpb=9bd01b5ed9029cd66faf8934d13542b75e598531 diff --git a/doc/man/lttng-track.1.txt b/doc/man/lttng-track.1.txt index 646b55cad..fd854c03c 100644 --- a/doc/man/lttng-track.1.txt +++ b/doc/man/lttng-track.1.txt @@ -1,204 +1,340 @@ lttng-track(1) ============== -:revdate: 04 November 2019 +:revdate: 14 June 2021 NAME ---- -lttng-track - Add one or more entries to an LTTng resource tracker +lttng-track - Allow specific processes to record LTTng events SYNOPSIS -------- +Allow specific processes to record Linux kernel events: + +[verse] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* 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)'] *track* (option:--kernel | option:--userspace) - [option:--session='SESSION'] (option:--pid='PID'[,'PID']... | - option:--uid='UID'[,'UID'][,'USERNAME']... | - option:--gid='GID'[,'GID'][,'GROUPNAME']... | - option:--vpid='VPID'[,'VPID']... | - option:--vuid='VUID'[,'VUID'][,'USERNAME']... | - option:--vgid='VGID'[,'VGID'][,'GROUPNAME']... | - option:--all (option:--pid | option:--uid | option:--gid | option:--vpid | option:--vuid | option:--vgid)) +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION'] + option:--all (option:--pid | option:--vpid | option:--uid | option:--vuid | option:--gid | option:--vgid)... + +Allow specific processes to record user space events: + +[verse] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION'] + (option:--vpid=VPID[,VPID]... | option:--vuid=VUSER[,VUSER]... | + option:--vgid=VGROUP[,VGROUP]...)... + +[verse] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION'] + option:--all (option:--vpid | option:--vgid | option:--vuid)... DESCRIPTION ----------- -The `lttng track` commands adds one or more entries to a -resource tracker. +The `lttng track` command allows one or more processes to record LTTng +events based on their attributes within: + +With the option:--session='SESSION' option:: + The recording session named 'SESSION'. + +Without the option:--session option:: + The current recording session (see man:lttng-concepts(7) to learn + more about the current recording session). -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)). +See man:lttng-concepts(7) to learn more about recording sessions and +recording event rules. -Tracker entries can be removed from the whitelist with -man:lttng-untrack(1). +The `track` command adds values to _inclusion sets_ of process +attributes. The available inclusion sets are, for a given recording +session: + +With the option:--kernel option:: ++ +* Process ID (PID). + +* Virtual process ID (VPID). ++ +This is the PID as seen by the application. + +* Unix user ID (UID). + +* Virtual Unix user ID (VUID). ++ +This is the UID as seen by the application. + +* Unix group ID (GID). + +* Virtual Unix group ID (VGID). ++ +This is the GID as seen by the application. -The following tracker are available: PID, UID, GID, VPID, VUID, VGID. +With the option:--userspace option:: ++ +* VPID +* VUID +* VGID + +When an event{nbsp}__E__ satisfies all the other explicit and implicit +conditions of an event rule{nbsp}__ER__, __ER__ matches{nbsp}__E__ if +the attributes of the process for which LTTng creates{nbsp}__E__ are +*all* part of the inclusion sets of the recording session and domain +of{nbsp}__ER__. + +By default, on recording session creation (see man:lttng-create(1)), +all processes are allowed to record events. In other words, all the +inclusion sets of the recording session contain all the possible +process attribute values. + +If a given inclusion set{nbsp}__IS__ contains all the possible values +(option:--all option), then using the `track` command to add one or more +values{nbsp}__V__ to{nbsp}__IS__: + +. Removes all the values from{nbsp}__IS__. ++ +This effectively makes{nbsp}__IS__ empty. -A tracker follows one or more IDs; only the processes with a tracked ID are -allowed to emit events. By default, all possible IDs on the system are tracked: -any process may emit enabled events (equivalent of `lttng track --pid --uid ---gid --vpid --vuid --vgid --all` for all domains). +. Adds{nbsp}__V__ to{nbsp}__IS__. -With the PID tracker, it is possible, for example, to record all system -calls called by a given process: +Example: with the PID inclusion set, you can record all the system calls +of a given process: [role="term"] ---- -# lttng enable-event --kernel --all --syscall -# lttng track --kernel --pid=2345 -# lttng start +$ 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. +See the ``<>'' section below for usage examples. + +Remove values from an inclusion set with the man:lttng-untrack(1) +command. -Example -~~~~~~~ -Assume the maximum system VPID is 7 for this example. +Inclusion set example +~~~~~~~~~~~~~~~~~~~~~ +This example operates on the Linux kernel process ID (PID) inclusion set +of the current recording session to show how an inclusion set works. -Initial whitelist: +Assume the maximum system PID is 7 for this example. +. Initial inclusion set: ++ ------------------------------- [0] [1] [2] [3] [4] [5] [6] [7] ------------------------------- -Command: - +. Command: ++ [role="term"] ---- -$ lttng track --userspace --vpid=3,6,7 +$ lttng track --kernel --pid=3,6,7 ---- - -Whitelist: - ++ +Inclusion set is now: ++ ------------------------------- [ ] [ ] [ ] [3] [ ] [ ] [6] [7] ------------------------------- -Command: - +. Command: ++ [role="term"] ---- -$ lttng untrack --userspace --vpid=7 +$ lttng untrack --kernel --pid=7 ---- - -Whitelist: - ++ +Inclusion set is now: ++ ------------------------------- [ ] [ ] [ ] [3] [ ] [ ] [6] [ ] ------------------------------- -Command: - +. Command: ++ [role="term"] ---- -$ lttng track --userspace --vpid=1,5 +$ lttng track --kernel --pid=1,5 ---- - -Whitelist: - ++ +Inclusion set is now: ++ ------------------------------- [ ] [1] [ ] [3] [ ] [5] [6] [ ] ------------------------------- -It should be noted that the VPID tracker tracks the numeric namespaced 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. +Remove values from an inclusion set with the man:lttng-untrack(1) +command. -include::common-cmd-options-head.txt[] +include::common-lttng-cmd-options-head.txt[] -Domain -~~~~~~ +Tracing domain +~~~~~~~~~~~~~~ One of: option:-k, option:--kernel:: - Track resources in the Linux kernel domain. + Add values to one or more Linux kernel inclusion sets. option:-u, option:--userspace:: - Track resources in the user space domain. - + Add values to one or more user space inclusion sets. -Target -~~~~~~ +Recording target +~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: - Track resources in the tracing session named 'SESSION' instead of - the current tracing session. + Add values to one or more inclusion sets of the recording session + named 'SESSION' instead of the current recording session. -Tracking -~~~~~~~~ -option:-a, option:--all:: - Used in conjunction with an empty tracker option, e.g: options:--pid track _all_ - process IDs (add all entries to the whitelist). - +Inclusion set selection +~~~~~~~~~~~~~~~~~~~~~~~ option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]:: - Track process IDs 'PID' (add them to the current whitelist). - PID is the non-namespaced value for the process. + For each 'PID' argument, add 'PID' to 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)). + -The 'PID' argument must be omitted when also using the option:--all -option. +Only available with option:--kernel option. -option:-p ['UID'[,'UID']...], option:--uid[='UID'[,'UID'][,'USERNAME']...]:: - Track process IDs 'UID' (add them to the current whitelist). - User name can also be used, name resolution is performed by - lttng-sessiond. - UID is the non-namespaced user id value for the process. +option:--vpid[='VPID'[,'VPID']...]:: + For each 'VPID' argument, add 'VPID' to the virtual process ID + inclusion set of the selected recording session and domain. + -The 'UID' argument must be omitted when also using the option:--all -option. +'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:-p ['GID'[,'GID']...], option:--gid[='GID'[,'GID'][,'GROUPNAME']...]:: - Track process IDs 'GID' (add them to the current whitelist). - Group name can also be used, name resolution is performed by - lttng-sessiond. - GID is the non-namespaced group id value for the process. +option:--uid[='USER'[,'USER']...]:: + For each 'USER' argument, add 'USER' to the user ID inclusion set of + the selected recording session and domain. + -The 'GID' argument must be omitted when also using the option:--all -option. +'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)). -option:-p ['VPID'[,'VPID']...], option:--vpid[='VPID'[,'VPID']...]:: - Track process IDs 'VPID' (add them to the current whitelist). - VPID is the namespaced PID of the process for its current context. +* A user name. ++ +The connected LTTng session daemon (see man:lttng-sessiond(8)) performs +the user name resolution on addition to the user ID inclusion set. +-- + -The 'VPID' argument must be omitted when also using the option:--all -option. +Only available with option:--kernel option. -option:-p ['VUID'[,'VUID']...], option:--vuid[='VUID'[,'VUID'][,'USERNAME']...]:: - Track process IDs 'VUID' (add them to the current whitelist). - User name can also be used, name resolution is performed by - lttng-sessiond. - VUID is the namespaced UID of the process for its current context. +option:--vuid[='VUSER'[,'VUSER']...]:: + For each 'VUSER' argument, add 'VUSER' to the virtual user ID + inclusion set of the selected recording session and domain. ++ +'VUSER' is either: + -The 'VUID' argument must be omitted when also using the option:--all -option. +-- +* The real user ID (see man:getuid(3)) of a process as seen + from the user namespace (see man:user_namespaces(7)). -option:-p ['VGID'[,'VGID']...], option:--vgid[='VGID'[,'VGID'][,'GROUPNAME']...]:: - Track process IDs 'VGID' (add them to the current whitelist). - Group name can also be used, name resolution is performed by - lttng-sessiond. - VGID is the namespaced GID of the process for its current context. +* A user name. ++ +The connected LTTng session daemon (see man:lttng-sessiond(8)) performs +the user name resolution on addition to the virtual user ID inclusion +set. +-- + +option:--gid[='GROUP'[,'GROUP']...]:: + For each 'GROUP' argument, add 'GROUP' to the group ID + inclusion set of the selected recording session and domain. ++ +'GROUP' is either: + -The 'VGID' argument must be omitted when also using the option:--all -option. +-- +* 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 addition to the group ID inclusion set. +-- ++ +Only available with option:--kernel option. + +option:--vgid[='VGROUP'[,'VGROUP']...]:: + For each 'VGROUP' argument, add 'VGROUP' to 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)). + +* A group name. ++ +The connected LTTng session daemon (see man:lttng-sessiond(8)) performs +the group name resolution on addition to the virtual group ID inclusion +set. +-- + + +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: add *all* + the possible values to the selected inclusion sets. -include::common-cmd-help-options.txt[] + +include::common-lttng-cmd-help-options.txt[] + + +include::common-lttng-cmd-after-options.txt[] + + +[[examples]] +EXAMPLES +-------- +.Add the PIDs 1728 and 3775 to the Linux kernel process ID inclusion set of the current recording session. +==== +See the option:--pid option. + +[role="term"] +---- +$ lttng track --kernel --pid=1728,3775 +---- +==== + +.Add the ID of a specific user to the user space virtual user ID inclusion set of a specific recording session. +==== +See the option:--vuid and option:--session options. + +[role="term"] +---- +$ lttng track --userspace --session=my-session --vuid=http +---- +==== + +.Add all the possible group IDs to the Linux kernel group ID inclusion set of the current recording session. +==== +See the option:--all and option:--gid options. + +[role="term"] +---- +$ lttng track --kernel --all --gid +---- +==== -include::common-cmd-footer.txt[] +include::common-footer.txt[] SEE ALSO -------- +man:lttng(1), man:lttng-untrack(1), -man:lttng(1) +man:lttng-concepts(7)