lttng-track(1)
==============
+: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:--all option:--pid)
+*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).
+
+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:
-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)).
+With the option:--kernel option::
++
+* Process ID (PID).
+
+* Virtual process ID (VPID).
++
+This is the PID as seen by the application.
-Tracker entries can be removed from the whitelist with
-man:lttng-untrack(1).
+* Unix user ID (UID).
-As of this version, the only available tracker is the *PID tracker*. The
-process ID (PID) tracker follows one or more process IDs; only the
-processes with a tracked PID are allowed to emit events. By default, all
-possible PIDs on the system are tracked: any process may emit enabled
-events (equivalent of `lttng track --pid --all` for all domains).
+* Virtual Unix user ID (VUID).
++
+This is the UID as seen by the application.
-With the PID tracker, it is possible, for example, to record all system
-calls called by a given process:
+* 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
--------------------------------------------
+----
+$ 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 ``<<examples,EXAMPLES>>'' section below for usage examples.
+Remove values from an inclusion set with the man:lttng-untrack(1)
+command.
-Example
-~~~~~~~
-Assume the maximum system PID is 7 for this example.
-Initial whitelist:
+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:
-
+. Command:
++
[role="term"]
------------------------------------
-lttng track --userspace --pid=3,6,7
------------------------------------
-
-Whitelist:
-
+----
+$ lttng track --kernel --pid=3,6,7
+----
++
+Inclusion set is now:
++
-------------------------------
[ ] [ ] [ ] [3] [ ] [ ] [6] [7]
-------------------------------
-Command:
-
+. Command:
++
[role="term"]
----------------------------------
-lttng untrack --userspace --pid=7
----------------------------------
-
-Whitelist:
-
+----
+$ lttng untrack --kernel --pid=7
+----
++
+Inclusion set is now:
++
-------------------------------
[ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
-------------------------------
-Command:
-
+. Command:
++
[role="term"]
----------------------------------
-lttng track --userspace --pid=1,5
----------------------------------
-
-Whitelist:
-
+----
+$ lttng track --kernel --pid=1,5
+----
++
+Inclusion set is now:
++
-------------------------------
[ ] [1] [ ] [3] [ ] [5] [6] [ ]
-------------------------------
-It should be noted that the PID tracker tracks the numeric 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.
+Remove values from an inclusion set with the man:lttng-untrack(1)
+command.
-See the man:lttng-untrack(1) for more details about removing
-entries.
+include::common-lttng-cmd-options-head.txt[]
-include::common-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 option:--pid option: 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).
+ 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 'PID' argument must be omitted when also using the option:--all
-option.
+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
+----
+====
-include::common-cmd-help-options.txt[]
+.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)
projects / lttng-tools.git / blobdiff