lttng-track(1) ============== NAME ---- lttng-track - Add one or more property values to an LTTng process tracker SYNOPSIS -------- Track processes for Linux kernel channels: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION'] [option:--pid='PID'[,'PID']... | option:--pid option:--all] [option:--vpid='PID'[,'PID']... | option:--vpid option:--all] [option:--uid='USER'[,'USER']... | option:--uid option:--all] [option:--vuid='USER'[,'USER']... | option:--vuid option:--all] [option:--gid='GROUP'[,'GROUP']... | option:--gid option:--all] [option:--vgid='GROUP'[,'GROUP']... | option:--vgid option:--all] Track processes for user space channels: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION'] [option:--vpid='PID'[,'PID']... | option:--vpid option:--all] [option:--vuid='USER'[,'USER']... | option:--vuid option:--all] [option:--vgid='GROUP'[,'GROUP']... | option:--vgid option:--all] DESCRIPTION ----------- The `lttng track` commands adds one or more property values to an LTTng process tracker. A process tracker is a _whitelist_ of values of various process properties. Processes of which all the property values are in the whitelist are said to be _tracked_ and are allowed to emit events, provided those events are also targeted by enabled event rules (see man:lttng-enable-event(1)). You can remove process property values from the whitelist with man:lttng-untrack(1). The available process properties are: option:--pid:: Process ID as seen by the Linux kernel (root namespace). option:--uid:: User ID or name as seen by the Linux kernel (root namespace). option:--gid:: Group ID or name as seen by the Linux kernel (root namespace). option:--vpid:: Process ID as seen by the traced process. option:--vuid:: User ID or name as seen by the traced process. option:--vgid:: Group ID or name as seen by the traced process. With the option:--uid, option:--vuid, option:--gid, and option:--vgid options, when you use one or more user or group names, the LTTng session daemon process (see man:lttng-sessiond(8)) performs the name-to-ID lookup _once_ in the appropriate files in `/etc`. The option:--pid and option:--vpid options specify _numeric_ process IDs. Should a process with a given ID exit and a new process be assigned this same ID, then the latter would also be allowed to emit events. When you create a tracing session (see man:lttng-create(1)), all processes on the system are tracked: any process with any ID, user, and group may emit enabled events. This is the equivalent of using the option:--all option for each process property option. A process is only allowed to emit enabled events when _all_ its property values are part of the tracker's whitelist: its ID, its user ID, and its group ID. If all the values of a given property are tracked, which is the default state for each property and for all domains when creating a tracing session, then using the `lttng track` command with one or more specific property values has the effect of first removing all the property values from the whitelist, then adding the specified values. Understanding the whitelist ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Assume the maximum system PID is 7 for this example. Initial PID whitelist: ------------------------------- [0] [1] [2] [3] [4] [5] [6] [7] ------------------------------- Command: [role="term"] ---- $ lttng track --kernel --pid=3,6,7 ---- Whitelist: ------------------------------- [ ] [ ] [ ] [3] [ ] [ ] [6] [7] ------------------------------- Command: [role="term"] ---- $ lttng untrack --kernel --pid=7 ---- Whitelist: ------------------------------- [ ] [ ] [ ] [3] [ ] [ ] [6] [ ] ------------------------------- Command: [role="term"] ---- $ lttng track --kernel --pid=1,5 ---- Whitelist: ------------------------------- [ ] [1] [ ] [3] [ ] [5] [6] [ ] ------------------------------- See the man:lttng-untrack(1) for more details about removing property values from the whitelist. Usage examples ~~~~~~~~~~~~~~ Track processes with PID 2394 or 185 as seen from the kernel, any user, and any group for kernel channels: [role="term"] ---- $ lttng track --kernel --pid=2394,185 ---- Track processes with any PID, user name `janine` as seen from the traced process, and any group for user space channels: [role="term"] ---- $ lttng track --userspace --vuid=janine ---- Track processes with any PID, user ID 1000 or user name `mireille` as seen from the traced process, and any group for kernel channels: [role="term"] ---- $ lttng track --kernel --vuid=1000,mireille ---- Track processes with any PID, any user, and group name `http` as seen from the traced process for user space channels: [role="term"] ---- $ lttng track --userspace --vgid=http ---- include::common-cmd-options-head.txt[] Domain ~~~~~~ One of: option:-k, option:--kernel:: Track processes for Linux kernel channels. option:-u, option:--userspace:: Track processes for user space channels. Target ~~~~~~ option:-s 'SESSION', option:--session='SESSION':: Track processes in the tracing session named 'SESSION' instead of the current tracing session. Process property ~~~~~~~~~~~~~~~~ option:-a, option:--all:: Following any of the property options below (without an option's argument): add _all_ possible values of this property to the process tracker's whitelist. option:--gid[='GROUP'[,'GROUP']...]:: Add group ID or name 'GROUP', as seen by the Linux kernel (root namespace), to the tracker's whitelist. option:--pid[='PID'[,'PID']...]:: Add process ID 'PID', as seen by the Linux kernel (root namespace), to the tracker's whitelist. option:--uid[='USER'[,'USER']...]:: Add user ID or name 'USER', as seen by the Linux kernel (root namespace), to the tracker's whitelist. option:--vgid[='GROUP'[,'GROUP']...]:: Add group ID or name 'GROUP', as seen by the traced process, to the tracker's whitelist. option:--vpid[='PID'[,'PID']...]:: Add process ID 'VPID', as seen by the traced process, to the tracker's whitelist. option:--vuid[='USER'[,'USER']...]:: Add user ID or name 'USER', as seen by the traced process, to the tracker's whitelist. include::common-cmd-help-options.txt[] include::common-cmd-footer.txt[] SEE ALSO -------- man:lttng-untrack(1), man:lttng(1)