Update track/untrack man page

[lttng-tools.git] / doc / man / lttng-track.1.txt

lttng-track(1)
==============
:revdate: 04 November 2019


NAME
----
lttng-track - Add one or more entries to an LTTng resource tracker


SYNOPSIS
--------
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* (option:--kernel | option:--userspace)
      [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
-----------
The `lttng track` commands adds one or more entries to a
resource tracker.

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)).

Tracker entries can be removed from the whitelist with
man:lttng-untrack(1).

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
----

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.


Example
~~~~~~~
Assume the maximum system VPID is 7 for this example.

Initial whitelist:

-------------------------------
[0] [1] [2] [3] [4] [5] [6] [7]
-------------------------------

Command:

[role="term"]
----
$ lttng track --userspace --vpid=3,6,7
----

Whitelist:

-------------------------------
[ ] [ ] [ ] [3] [ ] [ ] [6] [7]
-------------------------------

Command:

[role="term"]
----
$ lttng untrack --userspace --vpid=7
----

Whitelist:

-------------------------------
[ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
-------------------------------

Command:

[role="term"]
----
$ lttng track --userspace --vpid=1,5
----

Whitelist:

-------------------------------
[ ] [1] [ ] [3] [ ] [5] [6] [ ]
-------------------------------

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 man:lttng-untrack(1) for more details about removing
entries.


include::common-cmd-options-head.txt[]


Domain
~~~~~~
One of:

option:-k, option:--kernel::
    Track resources in the Linux kernel domain.

option:-u, option:--userspace::
    Track resources in the user space domain.


Target
~~~~~~
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 tracker option, e.g: options:--pid track _all_
    process IDs (add all entries to the whitelist).

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[]


include::common-cmd-footer.txt[]


SEE ALSO
--------
man:lttng-untrack(1),
man:lttng(1)