lttng-track(1): add usage examples

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

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


NAME
----
lttng-untrack - Disallow specific processes to record LTTng events


SYNOPSIS
--------
Disallow specific processes to record Linux kernel events:

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* 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)'] *untrack* option:--kernel [option:--session='SESSION']
      option:--all (option:--pid | option:--vpid | option:--uid | option:--vuid | option:--gid | option:--vgid)...

Disallow specific processes to record user space events:

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace [option:--session='SESSION']
      (option:--vpid=VPID[,VPID]... | option:--vuid=VUSER[,VUSER]... |
       option:--vgid=VGROUP[,VGROUP]...)...

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace [option:--session='SESSION']
      option:--all (option:--vpid | option:--vgid | option:--vuid)...


DESCRIPTION
-----------
The `lttng untrack` command disallows 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 `untrack` command removes values from _inclusion sets_ of process
attributes. See man:lttng-track(1) to learn more about inclusion sets.


Example
~~~~~~~
A common operation is to create a tracing session (see
man:lttng-create(1)), remove all the entries from the PID tracker
inclusion set, start tracing, and then manually track PIDs while the
tracing session is active.

Assume the maximum system PID is 7 for this example.

. Command:
+
[role="term"]
----
$ lttng create
----
+
Initial inclusion set:
+
-------------------------------
[0] [1] [2] [3] [4] [5] [6] [7]
-------------------------------

. Command:
+
[role="term"]
----
$ lttng untrack --kernel --pid --all
----
+
Inclusion set:
+
-------------------------------
[ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
-------------------------------

. Commands:
+
[role="term"]
----
$ lttng enable-event --kernel ...
$ lttng start
$ # ...
$ lttng track --kernel --pid=3,5
----
+
Inclusion set:
+
-------------------------------
[ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
-------------------------------

. Command:
+
[role="term"]
----
$ lttng track --kernel --pid=2
----
+
Inclusion set:
+
-------------------------------
[ ] [ ] [2] [3] [ ] [5] [ ] [ ]
-------------------------------


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


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

option:-k, option:--kernel::
    Remove values from one or more Linux kernel inclusion sets.

option:-u, option:--userspace::
    Remove values from one or more user space inclusion sets.


Recording target
~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
    Remove values from 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, remove 'PID' from 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, remove 'VPID' from 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, remove 'USER' from 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 removal from the user ID inclusion set.
--
+
Only available with option:--kernel option.

option:--vuid[='VUSER'[,'VUSER']...]::
    For each 'VUSER' argument, remove 'VUSER' from 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 removal from the virtual user ID inclusion
set.
--

option:--gid[='GROUP'[,'GROUP']...]::
    For each 'GROUP' argument, remove 'GROUP' from 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 removal from the group ID inclusion set.
--
+
Only available with option:--kernel option.

option:--vgid[='VGROUP'[,'VGROUP']...]::
    For each 'VGROUP' argument, remove 'VGROUP' from 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 removal from 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: clear 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-track(1),
man:lttng-concepts(7)