doc/man: create lttng-track(1) and update/fix content

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
index 2909b67e76e5411c6434355e1413ec01edb75d49..ea307aed8cec1b3574fc552938c21716fdc0d1e8 100644 (file)
--- a/doc/man/Makefile.am
+++ b/doc/man/Makefile.am
@@ -22,7 +22,8 @@ MAN1_NAMES = \
        lttng-disable-channel \
        lttng-add-context \
        lttng-list \
        lttng-disable-channel \
        lttng-add-context \
        lttng-list \

-       lttng-calibrate
+       lttng-calibrate \
+       lttng-track

 MAN3_NAMES =
 MAN8_NAMES =
 MAN1_NO_ASCIIDOC_NAMES = lttng-crash
 MAN3_NAMES =
 MAN8_NAMES =
 MAN1_NO_ASCIIDOC_NAMES = lttng-crash

diff --git a/doc/man/lttng-track.1.txt b/doc/man/lttng-track.1.txt
new file mode 100644 (file)
index 0000000..899a6c4
--- /dev/null
+++ b/doc/man/lttng-track.1.txt
@@ -0,0 +1,148 @@
+lttng-track(1)
+==============
+
+
+NAME
+----
+lttng-track - Add one or more entries to an LTTng resource tracker
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *track* (option:--kernel | option:--userspace)
+      [option:--session='SESSION'] (option:--pid='PID'[,'PID']... | option:--all option:--pid)
+
+
+DESCRIPTION
+-----------
+The `lttng track` commands adds one or more entries to a
+resource 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 linklttng:lttng-enable-event(1)).
+
+Tracker entries can be removed from the whitelist with
+linklttng: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).
+
+With the PID tracker, it is possible, for example, to record all system
+calls called by a given process:
+
+-------------------------------------------
+lttng enable-event --kernel --all --syscall
+lttng track --kernel --pid=2345
+lttng start
+-------------------------------------------
+
+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.
+
+
+Example
+~~~~~~~
+Assume the maximum system PID is 7 for this example.
+
+Initial whitelist:
+
+-------------------------------
+[0] [1] [2] [3] [4] [5] [6] [7]
+-------------------------------
+
+Command:
+
+-----------------------------------
+lttng track --userspace --pid=3,6,7
+-----------------------------------
+
+Whitelist:
+
+-------------------------------
+[ ] [ ] [ ] [3] [ ] [ ] [6] [7]
+-------------------------------
+
+Command:
+
+---------------------------------
+lttng untrack --userspace --pid=7
+---------------------------------
+
+Whitelist:
+
+-------------------------------
+[ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
+-------------------------------
+
+Command:
+
+---------------------------------
+lttng track --userspace --pid=1,5
+---------------------------------
+
+Whitelist:
+
+-------------------------------
+[ ] [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 linklttng:lttng-untrack(1) for more details about removing
+entries.
+
+
+include::common-cmd-options-head.txt[]
+
+
+Domain
+~~~~~~
+One of:
+
+option:-k, option:--kernel::
+    Track resources in the Linux kernel domain.
+
+option:-u, option:--userspace::
+    Track resources in the user space domain.
+
+
+Target
+~~~~~~
+option:-s, option:--session='SESSION'::
+    Track resources in the tracing session named 'SESSION' instead of
+    the current tracing session.
+
+
+Tracking
+~~~~~~~~
+option:-a, option:--all::
+    Used in conjunction with an empty option:--pid option: track _all_
+    process IDs (add all entries to the whitelist).
+
+option:-p, 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.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-untrack(1),
+linklttng:lttng(1)