Backport: lttng-track(1), lttng-untrack(1): document new properties/options

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

diff --git a/configure.ac b/configure.ac
index 3da818b9101d8f4a354ba085a9ff78cf53754736..04dbb859008c102f0facdff0321fbec60ca2186b 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -318,8 +318,8 @@ _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SNAPSHOT], [Snapshot buffers of current t
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_START], [Start tracing])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STATUS], [Get the status of the current tracing session])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STOP], [Stop tracing])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_START], [Start tracing])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STATUS], [Get the status of the current tracing session])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STOP], [Stop tracing])

-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_TRACK], [Track specific system resources])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_UNTRACK], [Untrack specific system resources])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_TRACK], [Track specific processes])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_UNTRACK], [Untrack specific processes])

 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_VERSION], [Show version information])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_VIEW], [Start trace viewer])
 
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_VERSION], [Show version information])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_VIEW], [Start trace viewer])
 

diff --git a/doc/man/lttng-track.1.txt b/doc/man/lttng-track.1.txt
index f5696f0c22e4030aaba985447d5b2681220ca01b..cf8466a5139e0a28a2083ab8f9a1a12ce465ca11 100644 (file)
--- a/doc/man/lttng-track.1.txt
+++ b/doc/man/lttng-track.1.txt
@@ -4,56 +4,95 @@ lttng-track(1)
 
 NAME
 ----
 
 NAME
 ----

-lttng-track - Add one or more entries to an LTTng resource tracker
+lttng-track - Add one or more property values to an LTTng process tracker

 
 
 SYNOPSIS
 --------
 
 
 SYNOPSIS
 --------

+Track processes for Linux kernel channels:
+
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION']
+      [option:--pid='PID'[,'PID']... | option:--pid option:--all]
+      [option:--vpid='PID'[,'PID']... | option:--vpid option:--all]
+      [option:--uid='USER'[,'USER']... | option:--uid option:--all]
+      [option:--vuid='USER'[,'USER']... | option:--vuid option:--all]
+      [option:--gid='GROUP'[,'GROUP']... | option:--gid option:--all]
+      [option:--vgid='GROUP'[,'GROUP']... | option:--vgid option:--all]
+
+Track processes for user space channels:
+

 [verse]
 [verse]

-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* (option:--kernel | option:--userspace)
-      [option:--session='SESSION'] (option:--pid='PID'[,'PID']... | option:--all option:--pid)
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION']
+      [option:--vpid='PID'[,'PID']... | option:--vpid option:--all]
+      [option:--vuid='USER'[,'USER']... | option:--vuid option:--all]
+      [option:--vgid='GROUP'[,'GROUP']... | option:--vgid option:--all]

 
 
 DESCRIPTION
 -----------
 
 
 DESCRIPTION
 -----------

-The `lttng track` commands adds one or more entries to a
-resource tracker.
+The `lttng track` commands adds one or more property values to an LTTng
+process 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 tracker is a _whitelist_ of values of various process
+properties. Processes of which all the property values are in the
+whitelist are said to be _tracked_ and are allowed to emit events,
+provided those events are also targeted by enabled event rules (see
+man:lttng-enable-event(1)).

 
 

-Tracker entries can be removed from the whitelist with
+You can remove process property values from the whitelist with

 man:lttng-untrack(1).
 
 man:lttng-untrack(1).
 

-As of this version, the only available tracker is the *PID tracker*. The
-process ID (PID) tracker follows one or more process IDs; only the
-processes with a tracked PID are allowed to emit events. By default, all
-possible PIDs on the system are tracked: any process may emit enabled
-events (equivalent of `lttng track --pid --all` for all domains).
+The available process properties are:

 
 

-With the PID tracker, it is possible, for example, to record all system
-calls called by a given process:
+option:--pid::
+    Process ID as seen by the Linux kernel (root namespace).

 
 

-[role="term"]
--------------------------------------------
-lttng enable-event --kernel --all --syscall
-lttng track --kernel --pid=2345
-lttng start
--------------------------------------------
+option:--uid::
+    User ID or name as seen by the Linux kernel (root namespace).
+
+option:--gid::
+    Group ID or name as seen by the Linux kernel (root namespace).
+
+option:--vpid::
+    Process ID as seen by the traced process.
+
+option:--vuid::
+    User ID or name as seen by the traced process.
+
+option:--vgid::
+    Group ID or name as seen by the traced process.
+
+With the option:--uid, option:--vuid, option:--gid, and option:--vgid
+options, when you use one or more user or group names, the LTTng session
+daemon process (see man:lttng-sessiond(8)) performs the name-to-ID
+lookup _once_ in the appropriate files in `/etc`.
+
+The option:--pid and option:--vpid options specify _numeric_ process
+IDs. Should a process with a given ID exit and a new process be assigned
+this same ID, then the latter would also be allowed to emit events.

 
 

-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.
+When you create a tracing session (see man:lttng-create(1)), all
+processes on the system are tracked: any process with any ID, user, and
+group may emit enabled events. This is the equivalent of using the
+option:--all option for each process property option.

 
 

+A process is only allowed to emit enabled events when _all_ its property
+values are part of the tracker's whitelist: its ID, its user ID, and its
+group ID.

 
 

-Example
-~~~~~~~
+If all the values of a given property are tracked, which is the default
+state for each property and for all domains when creating a tracing
+session, then using the `lttng track` command with one or more specific
+property values has the effect of first removing all the property values
+from the whitelist, then adding the specified values.
+
+
+Understanding the whitelist
+~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Assume the maximum system PID is 7 for this example.
 
 Assume the maximum system PID is 7 for this example.
 

-Initial whitelist:
+Initial PID whitelist:

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


@@ -62,9 +101,9 @@ Initial whitelist:
 Command:
 
 [role="term"]
 Command:
 
 [role="term"]

------------------------------------
-lttng track --userspace --pid=3,6,7
------------------------------------
+----
+$ lttng track --kernel --pid=3,6,7
+----

 
 Whitelist:
 
 
 Whitelist:
 


@@ -75,9 +114,9 @@ Whitelist:
 Command:
 
 [role="term"]
 Command:
 
 [role="term"]

----------------------------------
-lttng untrack --userspace --pid=7
----------------------------------
+----
+$ lttng untrack --kernel --pid=7
+----

 
 Whitelist:
 
 
 Whitelist:
 


@@ -88,9 +127,9 @@ Whitelist:
 Command:
 
 [role="term"]
 Command:
 
 [role="term"]

----------------------------------
-lttng track --userspace --pid=1,5
----------------------------------
+----
+$ lttng track --kernel --pid=1,5
+----

 
 Whitelist:
 
 
 Whitelist:
 


@@ -98,12 +137,43 @@ Whitelist:
 [ ] [1] [ ] [3] [ ] [5] [6] [ ]
 -------------------------------
 
 [ ] [1] [ ] [3] [ ] [5] [6] [ ]
 -------------------------------
 

-It should be noted that the PID tracker tracks the numeric 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 property
+values from the whitelist.

 
 

-See the man:lttng-untrack(1) for more details about removing
-entries.
+
+Usage examples
+~~~~~~~~~~~~~~
+Track processes with PID 2394 or 185 as seen from the kernel, any user,
+and any group for kernel channels:
+
+[role="term"]
+----
+$ lttng track --kernel --pid=2394,185
+----
+
+Track processes with any PID, user name `janine` as seen from the
+traced process, and any group for user space channels:
+
+[role="term"]
+----
+$ lttng track --userspace --vuid=janine
+----
+
+Track processes with any PID, user ID 1000 or user name `mireille` as
+seen from the traced process, and any group for kernel channels:
+
+[role="term"]
+----
+$ lttng track --kernel --vuid=1000,mireille
+----
+
+Track processes with any PID, any user, and group name `http` as seen
+from the traced process for user space channels:
+
+[role="term"]
+----
+$ lttng track --userspace --vgid=http
+----

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


@@ -114,31 +184,49 @@ Domain
 One of:
 
 option:-k, option:--kernel::
 One of:
 
 option:-k, option:--kernel::

-    Track resources in the Linux kernel domain.
+    Track processes for Linux kernel channels.

 
 option:-u, option:--userspace::
 
 option:-u, option:--userspace::

-    Track resources in the user space domain.
+    Track processes for user space channels.

 
 
 Target
 ~~~~~~
 option:-s 'SESSION', option:--session='SESSION'::
 
 
 Target
 ~~~~~~
 option:-s 'SESSION', option:--session='SESSION'::

-    Track resources in the tracing session named 'SESSION' instead of
+    Track processes in the tracing session named 'SESSION' instead of

     the current tracing session.
 
 
     the current tracing session.
 
 

-Tracking
-~~~~~~~~
+Process property
+~~~~~~~~~~~~~~~~

 option:-a, option:--all::
 option:-a, option:--all::

-    Used in conjunction with an empty option:--pid option: track _all_
-    process IDs (add all entries to the whitelist).
+    Following any of the property options below (without an option's
+    argument): add _all_ possible values of this property to the process
+    tracker's whitelist.
+
+option:--gid[='GROUP'[,'GROUP']...]::
+    Add group ID or name 'GROUP', as seen by the Linux kernel (root
+    namespace), to the tracker's whitelist.
+
+option:--pid[='PID'[,'PID']...]::
+    Add process ID 'PID', as seen by the Linux kernel (root namespace),
+    to the tracker's whitelist.
+
+option:--uid[='USER'[,'USER']...]::
+    Add user ID or name 'USER', as seen by the Linux kernel (root
+    namespace), to the tracker's whitelist.
+
+option:--vgid[='GROUP'[,'GROUP']...]::
+    Add group ID or name 'GROUP', as seen by the traced process, to the
+    tracker's whitelist.

 
 

-option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
-    Track process IDs 'PID' (add them to the current whitelist).
-+
-The 'PID' argument must be omitted when also using the option:--all
-option.
+option:--vpid[='PID'[,'PID']...]::
+    Add process ID 'VPID', as seen by the traced process, to the
+    tracker's whitelist.

 
 

+option:--vuid[='USER'[,'USER']...]::
+    Add user ID or name 'USER', as seen by the traced process, to the
+    tracker's whitelist.

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

diff --git a/doc/man/lttng-untrack.1.txt b/doc/man/lttng-untrack.1.txt
index d383740eb851e779be76221b8d6d418db058ee38..3a6762aac41a9f94a2d5ee27e325754b770f569d 100644 (file)
--- a/doc/man/lttng-untrack.1.txt
+++ b/doc/man/lttng-untrack.1.txt
@@ -4,46 +4,81 @@ lttng-untrack(1)
 
 NAME
 ----
 
 NAME
 ----

-lttng-untrack - Remove one or more entries from an LTTng resource tracker
+lttng-untrack - Remove one or more property values from an LTTng process tracker

 
 
 SYNOPSIS
 --------
 [verse]
 
 
 SYNOPSIS
 --------
 [verse]

-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* (option:--kernel | option:--userspace)
-      [option:--session='SESSION'] (option:--pid='PID'[,'PID']... | option:--all option:--pid)
+Untrack processes for Linux kernel channels:
+
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel [option:--session='SESSION']
+      [option:--pid='PID'[,'PID']... | option:--pid option:--all]
+      [option:--vpid='PID'[,'PID']... | option:--vpid option:--all]
+      [option:--uid='USER'[,'USER']... | option:--uid option:--all]
+      [option:--vuid='USER'[,'USER']... | option:--vuid option:--all]
+      [option:--gid='GROUP'[,'GROUP']... | option:--gid option:--all]
+      [option:--vgid='GROUP'[,'GROUP']... | option:--vgid option:--all]
+
+Untrack processes for user space channels:
+
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace [option:--session='SESSION']
+      [option:--vpid='PID'[,'PID']... | option:--vpid option:--all]
+      [option:--vuid='USER'[,'USER']... | option:--vuid option:--all]
+      [option:--vgid='GROUP'[,'GROUP']... | option:--vgid option:--all]

 
 
 DESCRIPTION
 -----------
 
 
 DESCRIPTION
 -----------

-The `lttng untrack` commands removes one or more entries from a
-resource tracker.
+The `lttng untrack` commands removes one or more property values from an
+LTTng process tracker.
+
+See man:lttng-track(1) to learn more about LTTng process trackers.
+
+The `lttng untrack` command removes specific property values from a
+process tracker's whitelist. The property values to remove must have
+been precedently added by man:lttng-track(1). It is also possible to
+remove all the values of a given property from the whitelist with the
+option:--all option following the specific property option.

 
 

-See man:lttng-track(1) to learn more about LTTng trackers.
+The available process properties are:

 
 

-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.
+option:--pid::
+    Process ID as seen by the Linux kernel (root namespace).

 
 

-As of this version, the only available tracker is the PID tracker.
+option:--uid::
+    User ID or name as seen by the Linux kernel (root namespace).

 
 

+option:--gid::
+    Group ID or name as seen by the Linux kernel (root namespace).

 
 

-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
-while tracing is active.
+option:--vpid::
+    Process ID as seen by the traced process.
+
+option:--vuid::
+    User ID or name as seen by the traced process.
+
+option:--vgid::
+    Group ID or name as seen by the traced process.
+
+
+Understanding the whitelist
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+One common operation is to create a tracing session (see
+man:lttng-create(1)), remove all the process ID property values from the
+process tracker whitelist, start tracing, and then manually track
+processes with a given PID while tracing is active.

 
 Assume the maximum system PID is 7 for this example.
 
 Command:
 
 [role="term"]
 
 Assume the maximum system PID is 7 for this example.
 
 Command:
 
 [role="term"]

-------------
-lttng create
-------------
+----
+$ lttng create
+----

 
 Initial whitelist:
 
 
 Initial whitelist:
 


@@ -54,9 +89,9 @@ Initial whitelist:
 Command:
 
 [role="term"]
 Command:
 
 [role="term"]

--------------------------------------
-lttng untrack --userspace --pid --all
--------------------------------------
+----
+$ lttng untrack --kernel --pid --all
+----

 
 Whitelist:
 
 
 Whitelist:
 


@@ -67,12 +102,12 @@ Whitelist:
 Commands:
 
 [role="term"]
 Commands:
 
 [role="term"]

-----------------------------------
-lttng enable-event --userspace ...
-lttng start
-# ...
-lttng track --userspace --pid=3,5
-----------------------------------
+----
+$ lttng enable-event --kernel ...
+$ lttng start
+$ # ...
+$ lttng track --kernel --pid=3,5
+----

 
 Whitelist:
 
 
 Whitelist:
 


@@ -83,9 +118,9 @@ Whitelist:
 Command:
 
 [role="term"]
 Command:
 
 [role="term"]

--------------------------------
-lttng track --userspace --pid=2
--------------------------------
+----
+$ lttng track --kernel --pid=2
+----

 
 Whitelist:
 
 
 Whitelist:
 


@@ -102,30 +137,49 @@ Domain
 One of:
 
 option:-k, option:--kernel::
 One of:
 
 option:-k, option:--kernel::

-    Untrack resources tracked in the Linux kernel domain.
+    Untrack processes for Linux kernel channels.

 
 option:-u, option:--userspace::
 
 option:-u, option:--userspace::

-    Untrack resources tracked in the user space domain.
+    Untrack processes for user space channels.

 
 
 Target
 ~~~~~~
 option:-s, option:--session='SESSION'::
 
 
 Target
 ~~~~~~
 option:-s, option:--session='SESSION'::

-    Untrack resources in the tracing session named 'SESSION' instead of
+    Untrack processes in the tracing session named 'SESSION' instead of

     the current tracing session.
 
 
     the current tracing session.
 
 

-Untracking
-~~~~~~~~~~
+Process property
+~~~~~~~~~~~~~~~~

 option:-a, option:--all::
 option:-a, option:--all::

-    Used in conjunction with an empty option:--pid option: untrack _all_
-    process IDs (clear the whitelist).
-
-option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
-    Untrack process IDs 'PID' (remove them from the current whitelist).
-+
-The 'PID' argument must be omitted when also using the option:--all
-option.
+    Following any of the property options below (without an option's
+    argument): remove _all_ possible values of this property from the
+    process tracker's whitelist.
+
+option:--pid[='PID'[,'PID']...]::
+    Remove process ID 'PID', as seen by the Linux kernel (root
+    namespace), from the tracker's whitelist.
+
+option:--uid[='USER'[,'USER']...]::
+    Remove user ID or name 'USER', as seen by the Linux kernel (root
+    namespace), from the tracker's whitelist.
+
+option:--gid[='GROUP'[,'GROUP']...]::
+    Remove group ID or name 'GROUP', as seen by the Linux kernel (root
+    namespace), from the tracker's whitelist.
+
+option:--vpid[='PID'[,'PID']...]::
+    Remove process ID 'VPID', as seen by the traced process, from the
+    tracker's whitelist.
+
+option:--vuid[='USER'[,'USER']...]::
+    Remove user ID or name 'USER', as seen by the traced process, from
+    the tracker's whitelist.
+
+option:--vgid[='GROUP'[,'GROUP']...]::
+    Remove group ID or name 'GROUP', as seen by the traced process, from
+    the tracker's whitelist.

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