lttng-track(1) ============== :revdate: 4 March 2020 NAME ---- lttng-track - Add one or more values to an LTTng process attribute tracker SYNOPSIS -------- Add specific process attribute values to a Linux kernel domain tracker: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* 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]... )... Add all possible process attribute values to a Linux kernel domain tracker: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel option:--all (option:--pid | option:--vpid | option:--uid | option:--vuid | option:--gid | option:--vgid )... Add specific process attribute values to a user space domain tracker: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace (option:--vpid=VPID[,VPID]... | option:--vuid=VUID[,VUID]... | option:--vgid=VGID[,VGID]...)... Add all possible process attribute values to a user space domain tracker: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace option:--all (option:--vpid | option:--vgid | option:--vuid)... DESCRIPTION ----------- The `lttng track` commands adds one or more values to a process attribute tracker. A process attribute tracker is an _inclusion set_ of process attributes. Tracked processes are allowed to emit events, provided those events are targeted by enabled event rules (see man:lttng-enable-event(1)). Tracker values can be removed from an inclusion set with man:lttng-untrack(1). The available process attribute trackers are: * Process ID (PID) * Virtual PID (VPID) * User ID (UID) * Virtual UID (VUID) * Group ID (GID) * Virtual GID (VGID) A tracker follows one or more process attribute values; only the processes with a tracked value are allowed to emit events. By default, all possible values on the system are tracked: any process may emit enabled events, the equivalent of: [role="term"] ---- $ lttng track --kernel --pid --vpid --uid --vuid --gid --vgid --all $ lttng track --userspace --vpid --vuid --vgid --all ---- With the PID tracker, for example, you can record all system calls of a given process: [role="term"] ---- $ lttng enable-event --kernel --all --syscall $ lttng track --kernel --pid=2345 $ lttng start ---- If all the PIDs are tracked (with the option:--pid and option:--all options), 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 inclusion set, then adding the specified PIDs. Example ~~~~~~~ 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: ------------------------------- [ ] [ ] [ ] [3] [ ] [ ] [6] [7] ------------------------------- Command: [role="term"] ---- $ lttng untrack --kernel --pid=7 ---- inclusion set: ------------------------------- [ ] [ ] [ ] [3] [ ] [ ] [6] [ ] ------------------------------- Command: [role="term"] ---- $ lttng track --kernel --pid=1,5 ---- inclusion set: ------------------------------- [ ] [1] [ ] [3] [ ] [5] [6] [ ] ------------------------------- See the man:lttng-untrack(1) for more details about removing values from the inclusion set. include::common-cmd-options-head.txt[] Domain ~~~~~~ One of: option:-k, option:--kernel:: Track process attributes in the Linux kernel domain. option:-u, option:--userspace:: Track process attributes in the user space domain. Target ~~~~~~ option:-s 'SESSION', option:--session='SESSION':: Track process attributes in the tracing session named 'SESSION' instead of the current tracing session. Tracking ~~~~~~~~ option:-a, option:--all:: Used in conjunction with a single, empty option:--pid, option:--vpid, option:--uid, option:--vuid, option:--gid, or option:--vgid option: track _all_ possible process attribute values (add all values to the inclusion set). option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]:: Track process ID values 'PID' (add them to 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']...]:: Track virtual process ID values 'VPID' (add them to 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']...]:: Track user ID process attribute values 'USER' (add them to 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. The user name resolution is performed by the session daemon (see man:lttng-sessiond(8)) on addition to the user ID inclusion set. + The 'USER' argument must be omitted when also using the option:--all option. option:--vuid[='USER'[,'USER']...]:: Track virtual user ID process attribute values 'USER' (add them to 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. The user name resolution is performed by the session daemon (see man:lttng-sessiond(8)) on addition to the virtual user ID inclusion set. + The 'USER' argument must be omitted when also using the option:--all option. option:--gid[='GROUP'[,'GROUP']...]:: Track group ID process attribute values 'GROUP' (add them to 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. The group name resolution is performed by the session daemon (see man:lttng-sessiond(8)) on addition to the group ID inclusion set. + The 'GROUP' argument must be omitted when also using the option:--all option. option:--vgid[='GROUP'[,'GROUP']...]:: Track virtual group ID process attribute values 'GROUP'(add them to 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. The group name resolution is performed by the session daemon (see man:lttng-sessiond(8)) on addition to the virtual group ID inclusion set. + The 'GROUP' argument must be omitted when also using the option:--all option. include::common-cmd-help-options.txt[] include::common-cmd-footer.txt[] SEE ALSO -------- man:lttng-untrack(1), man:lttng(1)