lttng-track(1) ============== :revdate: 14 June 2021 NAME ---- 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:--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` 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). See man:lttng-concepts(7) to learn more about recording sessions and recording event rules. 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. 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. . Adds{nbsp}__V__ to{nbsp}__IS__. 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 ---- See the ``<>'' section below for usage examples. Remove values from an inclusion set with the man:lttng-untrack(1) command. 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. Assume the maximum system PID is 7 for this example. . Initial inclusion set: + ------------------------------- [0] [1] [2] [3] [4] [5] [6] [7] ------------------------------- . Command: + [role="term"] ---- $ lttng track --kernel --pid=3,6,7 ---- + Inclusion set is now: + ------------------------------- [ ] [ ] [ ] [3] [ ] [ ] [6] [7] ------------------------------- . Command: + [role="term"] ---- $ lttng untrack --kernel --pid=7 ---- + Inclusion set is now: + ------------------------------- [ ] [ ] [ ] [3] [ ] [ ] [6] [ ] ------------------------------- . Command: + [role="term"] ---- $ lttng track --kernel --pid=1,5 ---- + Inclusion set is now: + ------------------------------- [ ] [1] [ ] [3] [ ] [5] [6] [ ] ------------------------------- Remove values from an inclusion set with the man:lttng-untrack(1) command. include::common-lttng-cmd-options-head.txt[] Tracing domain ~~~~~~~~~~~~~~ One of: option:-k, option:--kernel:: Add values to one or more Linux kernel inclusion sets. option:-u, option:--userspace:: Add values to one or more user space inclusion sets. Recording target ~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: Add values to one or more inclusion sets of the recording session named 'SESSION' instead of the current recording session. Inclusion set selection ~~~~~~~~~~~~~~~~~~~~~~~ option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]:: 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)). + Only available with option:--kernel option. option:--vpid[='VPID'[,'VPID']...]:: For each 'VPID' argument, add 'VPID' to 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, add 'USER' to 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 addition to the user ID inclusion set. -- + Only available with option:--kernel option. 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 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 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 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-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-footer.txt[] SEE ALSO -------- man:lttng(1), man:lttng-untrack(1), man:lttng-concepts(7)