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

- Replace the term whitelist by "inclusion set"

  The use of whitelist (and its counterpart, blacklist) is somewhat
  controversial and doesn't align with the terms used in the tracker
  API.

  The "inclusion set" nomenclature is inspired by that used by ACL,
  namely "include list" and "exclude list". Set is preferred to list
  as there is no implied notion of order.

- Adapt process attribute descriptions

  The process attribute descriptions were apparently copy-pasted from
  the original PID description (all are referencing "process IDs").

  A suitable description is added for each process attribute.

- Add new process attributes to lttng-untrack(1)

  The lttng-untrack man page was not updated when the resource types
  introduced in LTTng 2.12 were added to lttng-track(1).

- Group all process attributes with their 'virtual' counter-parts

  The order in which process attributes were described was: pid, uid,
  gid, vpid, vuid, vgid.

  Grouping process attributes with their virtual counterpart (e.g. pid
  followed by vpid) makes it easier to understand the difference at a
  glance.

  The order becomes: pid, vpid, uid, vuid, gid, vgid

- Remove all PID-specific wordings in lttng-untrack(1)

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Change-Id: I46486c4e90003da3e860682f6c22a0e4a154492b

diff --git a/doc/man/lttng-track.1.txt b/doc/man/lttng-track.1.txt
index 646b55cad5fb6a93d7c4df903a59fcdbf79af116..79b294f74e1556bad5f35036b60855b0cbd5b5a9 100644 (file)
--- a/doc/man/lttng-track.1.txt
+++ b/doc/man/lttng-track.1.txt
@@ -1,67 +1,99 @@
 lttng-track(1)
 ==============
-:revdate: 04 November 2019
+:revdate: 4 March 2020
 
 
 NAME
 ----
-lttng-track - Add one or more entries to an LTTng resource tracker
+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:--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))
+*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 entries to a
-resource tracker.
+The `lttng track` commands adds one or more values to a
+process attribute 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)).
+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 entries can be removed from the whitelist with
+Tracker values can be removed from an inclusion set with
 man:lttng-untrack(1).
 
-The following tracker are available: PID, UID, GID, VPID, VUID, VGID.
+The available process attribute trackers are:
 
-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).
+* Process ID (PID)
+* Virtual PID (VPID)
+* User ID (UID)
+* Virtual UID (VUID)
+* Group ID (GID)
+* Virtual GID (VGID)
 
-With the PID tracker, it is possible, for example, to record all system
-calls called by a given process:
+
+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 enable-event --kernel --all --syscall
-# lttng track --kernel --pid=2345
-# lttng start
+$ lttng track --kernel --pid --vpid --uid --vuid --gid --vgid --all
+$ lttng track --userspace --vpid --vuid --vgid --all
 ----
 
-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.
+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 VPID is 7 for this example.
+Assume the maximum system PID is 7 for this example.
 
-Initial whitelist:
+Initial inclusion set:
 
 -------------------------------
 [0] [1] [2] [3] [4] [5] [6] [7]
@@ -71,10 +103,10 @@ Command:
 
 [role="term"]
 ----
-$ lttng track --userspace --vpid=3,6,7
+$ lttng track --kernel --pid=3,6,7
 ----
 
-Whitelist:
+inclusion set:
 
 -------------------------------
 [ ] [ ] [ ] [3] [ ] [ ] [6] [7]
@@ -84,10 +116,10 @@ Command:
 
 [role="term"]
 ----
-$ lttng untrack --userspace --vpid=7
+$ lttng untrack --kernel --pid=7
 ----
 
-Whitelist:
+inclusion set:
 
 -------------------------------
 [ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
@@ -97,21 +129,17 @@ Command:
 
 [role="term"]
 ----
-$ lttng track --userspace --vpid=1,5
+$ lttng track --kernel --pid=1,5
 ----
 
-Whitelist:
+inclusion set:
 
 -------------------------------
 [ ] [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.
+values from the inclusion set.
 
 
 include::common-cmd-options-head.txt[]
@@ -122,73 +150,104 @@ Domain
 One of:
 
 option:-k, option:--kernel::
-    Track resources in the Linux kernel domain.
+    Track process attributes in the Linux kernel domain.
 
 option:-u, option:--userspace::
-    Track resources in the user space domain.
+    Track process attributes in the user space domain.
 
 
 Target
 ~~~~~~
 option:-s 'SESSION', option:--session='SESSION'::
-    Track resources in the tracing session named 'SESSION' instead of
+    Track process attributes 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).
+    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 IDs 'PID' (add them to the current whitelist).
-    PID is the non-namespaced value for the process.
+    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:-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.
+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 'UID' argument must be omitted when also using the option:--all
+The 'VPID' 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.
+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 'GID' argument must be omitted when also using the option:--all
+The 'USER' 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.
+option:--vuid[='USER'[,'USER']...]::
+    Track virtual user ID process attribute values 'USER' (add them to
+    the virtual user ID inclusion set).
 +
-The 'VPID' argument must be omitted when also using the option:--all
+'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:-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.
+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.
 +
-The 'VUID' argument must be omitted when also using the option:--all
+'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:-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.
+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 'VGID' argument must be omitted when also using the option:--all
+The 'GROUP' argument must be omitted when also using the option:--all
 option.
 
 

diff --git a/doc/man/lttng-untrack.1.txt b/doc/man/lttng-untrack.1.txt
index 8d0fd1f60ae837a993dea87191e010a259bbe6fb..f1a8720249f50daf2669602375129064bcf32cd7 100644 (file)
--- a/doc/man/lttng-untrack.1.txt
+++ b/doc/man/lttng-untrack.1.txt
@@ -1,40 +1,62 @@
 lttng-untrack(1)
 ================
-:revdate: 14 March 2017
+:revdate: 4 March 2020
 
 
 NAME
 ----
-lttng-untrack - Remove one or more entries from an LTTng resource tracker
+lttng-untrack - Remove one or more values from an LTTng process attribute tracker
 
 
 SYNOPSIS
 --------
+Remove specific process attribute values from a Linux kernel domain tracker:
+
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* 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]... )...
+
+Remove all possible process attribute values from a Linux kernel domain tracker:
+
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel
+      option:--all (option:--pid | option:--vpid | option:--uid |
+      option:--vuid | option:--gid | option:--vgid )...
+
+Remove specific process attribute values from a user space domain tracker:
+
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace
+      (option:--vpid=VPID[,VPID]... | option:--vuid=VUID[,VUID]... | option:--vgid=VGID[,VGID]...)...
+
+Remove all possible process attribute values from a user space domain tracker:
+
 [verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* (option:--kernel | option:--userspace)
-      [option:--session='SESSION'] (option:--pid='PID'[,'PID']... | option:--all option:--pid)
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace
+      option:--all (option:--vpid | option:--vgid | option:--vuid)...
 
 
 DESCRIPTION
 -----------
-The `lttng untrack` commands removes one or more entries from a
-resource tracker.
+The `lttng untrack` commands removes one or more values from a
+process attribute tracker.
 
 See man:lttng-track(1) to learn more about LTTng trackers.
 
-The untrack command removes specific resources from a tracker. The
-resources to remove must have been precedently added by
-man:lttng-track(1). It is also possible to remove all the
-resources from the whitelist using the option:--all option.
-
-As of this version, the only available tracker is the PID tracker.
+The untrack command removes specific process attribute values from a
+tracker's inclusion set. The attributes to remove must have been
+precedently added by man:lttng-track(1). It is also possible to remove
+all the possible values of a process attribute from the inclusion set
+using the option:--all option.
 
 
 Example
 ~~~~~~~
 One common operation is to create a tracing session
 (see man:lttng-create(1)), remove all the entries from the PID
-tracker whitelist, start tracing, and then manually track PIDs
+tracker inclusion set, start tracing, and then manually track PIDs
 while tracing is active.
 
 Assume the maximum system PID is 7 for this example.
@@ -46,7 +68,7 @@ Command:
 $ lttng create
 ----
 
-Initial whitelist:
+Initial inclusion set:
 
 -------------------------------
 [0] [1] [2] [3] [4] [5] [6] [7]
@@ -56,10 +78,10 @@ Command:
 
 [role="term"]
 ----
-$ lttng untrack --userspace --pid --all
+$ lttng untrack --kernel --pid --all
 ----
 
-Whitelist:
+inclusion set:
 
 -------------------------------
 [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
@@ -69,13 +91,13 @@ Commands:
 
 [role="term"]
 ----
-$ lttng enable-event --userspace ...
+$ lttng enable-event --kernel ...
 $ lttng start
 $ # ...
-$ lttng track --userspace --pid=3,5
+$ lttng track --kernel --pid=3,5
 ----
 
-Whitelist:
+inclusion set:
 
 -------------------------------
 [ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
@@ -85,10 +107,10 @@ Command:
 
 [role="term"]
 ----
-$ lttng track --userspace --pid=2
+$ lttng track --kernel --pid=2
 ----
 
-Whitelist:
+inclusion set:
 
 -------------------------------
 [ ] [ ] [2] [3] [ ] [5] [ ] [ ]
@@ -103,31 +125,102 @@ Domain
 One of:
 
 option:-k, option:--kernel::
-    Untrack resources tracked in the Linux kernel domain.
+    Track process attributes in the Linux kernel domain.
 
 option:-u, option:--userspace::
-    Untrack resources tracked in the user space domain.
+    Track process attributes in the user space domain.
 
 
 Target
 ~~~~~~
-option:-s, option:--session='SESSION'::
-    Untrack resources in the tracing session named 'SESSION' instead of
-    the current tracing session.
+option:-s 'SESSION', option:--session='SESSION'::
+    Untrack process attributes in the tracing session named 'SESSION'
+    instead of the current tracing session.
 
 
 Untracking
 ~~~~~~~~~~
 option:-a, option:--all::
-    Used in conjunction with an empty option:--pid option: untrack _all_
-    process IDs (clear the whitelist).
+    Used in conjunction with a single, empty option:--pid,
+    option:--vpid, option:--uid, option:--vuid, option:--gid,
+    or option:--vgid option: untrack _all_ possible process attribute
+    values (remove all values from the inclusion set).
 
 option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
-    Untrack process IDs 'PID' (remove them from the current whitelist).
+    Untrack process ID values 'PID' (remove them from 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']...]::
+    Untrack virtual process ID values 'VPID' (remove them from 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']...]::
+    Untrack user ID process attribute values 'USER' (remove them from
+    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. No name resolution is performed;
+'USER' will be matched against the names in the inclusion set.
++
+The 'USER' argument must be omitted when also using the option:--all
+option.
+
+option:--vuid[='USER'[,'USER']...]::
+    Untrack virtual user ID process attribute values 'USER' (remove
+    them from 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. No name resolution is performed;
+'USER' will be matched against the names in the inclusion set.
++
+The 'USER' argument must be omitted when also using the option:--all
+option.
+
+option:--gid[='GROUP'[,'GROUP']...]::
+    Untrack group ID process attribute values 'GROUP' (remove them
+    from 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. No name resolution is performed;
+'GROUP' will be matched against the names in the inclusion set.
++
+The 'GROUP' argument must be omitted when also using the option:--all
+option.
+
+option:--vgid[='GROUP'[,'GROUP']...]::
+    Untrack virtual group ID process attribute values 'GROUP'(remove
+    them from 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. No name resolution is performed;
+'GROUP' will be matched against the names in the inclusion set.
++
+The 'GROUP' argument must be omitted when also using the option:--all
+option.
+
 
 include::common-cmd-help-options.txt[]