Docs: overhaul of lttng-track(1) and lttng-untrack(1)

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

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)