lttng-track(1)
==============
+:revdate: 04 November 2019
NAME
--------
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* (option:--kernel | option:--userspace)
- [option:--session='SESSION'] (option:--pid='PID'[,'PID']... | option:--all option:--pid)
+ [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))
DESCRIPTION
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 linklttng:lttng-enable-event(1)).
+event rules (see man:lttng-enable-event(1)).
Tracker entries can be removed from the whitelist with
-linklttng:lttng-untrack(1).
+man:lttng-untrack(1).
-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).
+The following tracker are available: PID, UID, GID, VPID, VUID, VGID.
+
+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).
With the PID tracker, it is possible, for example, to record all system
calls called by 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
Example
~~~~~~~
-Assume the maximum system PID is 7 for this example.
+Assume the maximum system VPID is 7 for this example.
Initial whitelist:
Command:
[role="term"]
------------------------------------
-lttng track --userspace --pid=3,6,7
------------------------------------
+----
+$ lttng track --userspace --vpid=3,6,7
+----
Whitelist:
Command:
[role="term"]
----------------------------------
-lttng untrack --userspace --pid=7
----------------------------------
+----
+$ lttng untrack --userspace --vpid=7
+----
Whitelist:
Command:
[role="term"]
----------------------------------
-lttng track --userspace --pid=1,5
----------------------------------
+----
+$ lttng track --userspace --vpid=1,5
+----
Whitelist:
[ ] [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.
+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 linklttng:lttng-untrack(1) for more details about removing
+See the man:lttng-untrack(1) for more details about removing
entries.
Target
~~~~~~
-option:-s, option:--session='SESSION'::
+option:-s 'SESSION', option:--session='SESSION'::
Track resources in the tracing session named 'SESSION' instead of
the current tracing session.
Tracking
~~~~~~~~
option:-a, option:--all::
- Used in conjunction with an empty option:--pid option: track _all_
+ Used in conjunction with an empty tracker option, e.g: options:--pid track _all_
process IDs (add all entries to the whitelist).
-option:-p, option:--pid[='PID'[,'PID']...]::
+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.
+
The 'PID' argument must be omitted when also using the option:--all
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.
++
+The 'UID' argument must be omitted when also using the option:--all
+option.
+
+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.
++
+The 'GID' argument must be omitted when also using the option:--all
+option.
+
+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.
++
+The 'VPID' argument must be omitted when also using the option:--all
+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.
++
+The 'VUID' argument must be omitted when also using the option:--all
+option.
+
+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.
++
+The 'VGID' argument must be omitted when also using the option:--all
+option.
+
include::common-cmd-help-options.txt[]
SEE ALSO
--------
-linklttng:lttng-untrack(1),
-linklttng:lttng(1)
+man:lttng-untrack(1),
+man:lttng(1)
projects / lttng-tools.git / blobdiff