lttng-clear(1): add usage examples

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

lttng-track(1)
==============
:revdate: 1 May 2021


NAME
----
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:--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` command allows one or more processes to record LTTng
events based on their attributes within:

With the option:--session='SESSION' option::
    The tracing session named 'SESSION'.

Without the option:--session option::
    The current tracing session (see man:lttng-concepts(7) to learn more
    about the current tracing session).

See man:lttng-concepts(7) to learn more about tracing sessions and
recording event rules.

The `track` command adds values to _inclusion sets_ of process
attributes. The available inclusion sets are, for a given tracing
session:

With the option:--kernel option::
+
* Process ID (PID).

* Virtual process ID (VPID).
+
This is the PID as seen by the application.

* Unix user ID (UID).

* Virtual Unix user ID (VUID).
+
This is the UID as seen by the application.

* 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 tracing session and domain
of{nbsp}__ER__.

By default, on tracing session creation (see man:lttng-create(1)),
all processes are allowed to record events. In other words, all the
inclusion sets of the tracing 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
----

Remove values from an inclusion set with the man:lttng-untrack(1)
command.


Inclusion set example
~~~~~~~~~~~~~~~~~~~~~
This example operates on the Linux kernel process ID (PID) inclusion set
of the current tracing 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:
+
[role="term"]
----
$ lttng track --kernel --pid=3,6,7
----
+
Inclusion set is now:
+
-------------------------------
[ ] [ ] [ ] [3] [ ] [ ] [6] [7]
-------------------------------

. Command:
+
[role="term"]
----
$ lttng untrack --kernel --pid=7
----
+
Inclusion set is now:
+
-------------------------------
[ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
-------------------------------

. Command:
+
[role="term"]
----
$ lttng track --kernel --pid=1,5
----
+
Inclusion set is now:
+
-------------------------------
[ ] [1] [ ] [3] [ ] [5] [6] [ ]
-------------------------------

Remove values from an inclusion set with the man:lttng-untrack(1)
command.


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


Tracing domain
~~~~~~~~~~~~~~
One of:

option:-k, option:--kernel::
    Add values to one or more Linux kernel inclusion sets.

option:-u, option:--userspace::
    Add values to one or more user space inclusion sets.

Recording target
~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
    Add values to one or more inclusion sets of the tracing session
    named 'SESSION' instead of the current tracing session.


Inclusion set selection
~~~~~~~~~~~~~~~~~~~~~~~
option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
    For each 'PID' argument, add 'PID' to the process ID inclusion set
    of the selected tracing 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 tracing 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 tracing 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 tracing 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 tracing 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 tracing 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 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[]


include::common-footer.txt[]


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