From: Philippe Proulx Date: Sat, 5 Sep 2015 01:22:52 +0000 (-0400) Subject: Document PID tracking feature X-Git-Url: https://git.lttng.org./?a=commitdiff_plain;h=e008a9af4276c37401466d0b23a92e1775f38e62;p=lttng-docs.git Document PID tracking feature Signed-off-by: Philippe Proulx --- diff --git a/contents/using-lttng/controlling-tracing/pid-tracking.md b/contents/using-lttng/controlling-tracing/pid-tracking.md new file mode 100644 index 0000000..3034f4f --- /dev/null +++ b/contents/using-lttng/controlling-tracing/pid-tracking.md @@ -0,0 +1,121 @@ +--- +id: pid-tracking +since: 2.7 +--- + +It's often useful to allow only specific process IDs (PIDs) to emit +enabled events. For example, you may wish to record all the system +calls made by a given process (à la +strace). + +The `lttng track` and `lttng untrack` commands serve this purpose. Both +commands operate on a whitelist of process IDs. The `track` command +adds entries to this whitelist while the `untrack` command removes +entries. Any process having one of the PIDs in the whitelist is allowed +to emit [enabled](#doc-enabling-disabling-events) LTTng events. + +
+

+ Note:The PID tracker tracks the + numeric process IDs. Should a process with a given tracked + ID exit and another process be given this ID, then the latter would + also be allowed to emit events. +

+
+ +For the sake of the following examples, assume the target system has 16 +possible PIDs. When a [tracing session](#doc-creating-destroying-tracing-sessions) +is created, the whitelist contains all the possible PIDs: + +
+All PIDs are tracked +
All PIDs are tracked
+
+ +When the whitelist is full and the `track` command is executed to specify +some PIDs to track, the whitelist is first cleared, then the specific +PIDs are tracked. For example, after + +
+lttng track --pid 3,4,7,10,13
+
+ +the whitelist is: + +
+PIDs 3, 4, 7, 10, and 13 are tracked +
PIDs 3, 4, 7, 10, and 13 are tracked
+
+ +More PIDs can be added to the whitelist afterwards: + +
+lttng track --pid 1,15,16
+
+ +gives: + +
+PIDs 1, 15, and 16 are added to the whitelist +
PIDs 1, 15, and 16 are added to the whitelist
+
+ +The `untrack` command removes entries from the PID tracker's whitelist. +Given the last example, the following command: + +
+lttng untrack --pid 3,7,10,13
+
+ +leads to this whitelist: + +
+PIDs 3, 7, 10, and 13 are removed from the whitelist +
PIDs 3, 7, 10, and 13 are removed from the whitelist
+
+ +All possible PIDs can be tracked again using the `--all` option of +`lttng track`: + +
+lttng track --pid --all
+
+ +gives: + +
+All PIDs are tracked +
All PIDs are tracked
+
+ +A very typical use case with PID tracking is starting with an empty +whitelist, then [starting the tracers](#doc-basic-tracing-session-control), +and then adding PIDs manually while tracing is active. This can be +accomplished by using the `--all` option of the `untrack` command +to clear the whitelist after a tracing session is created: + +
+lttng track --pid --all
+
+ +gives: + +
+No PIDs are tracked +
No PIDs are tracked
+
+ +Tracing with this whitelist configuration does not produce any event +because no processes are tracked. The `track` command can be used +as usual to track specific PIDs, for example: + +
+lttng track --pid 6,11
+
+ +results in: + +
+PIDs 6 and 11 are tracked +
PIDs 6 and 11 are tracked
+
diff --git a/images/export/track-1-3-4-7-10-13-15-16.png b/images/export/track-1-3-4-7-10-13-15-16.png new file mode 100644 index 0000000..68ed925 Binary files /dev/null and b/images/export/track-1-3-4-7-10-13-15-16.png differ diff --git a/images/export/track-1-4-15-16.png b/images/export/track-1-4-15-16.png new file mode 100644 index 0000000..d2ecb74 Binary files /dev/null and b/images/export/track-1-4-15-16.png differ diff --git a/images/export/track-3-4-7-10-13.png b/images/export/track-3-4-7-10-13.png new file mode 100644 index 0000000..ba40152 Binary files /dev/null and b/images/export/track-3-4-7-10-13.png differ diff --git a/images/export/track-6-11.png b/images/export/track-6-11.png new file mode 100644 index 0000000..f0a2f76 Binary files /dev/null and b/images/export/track-6-11.png differ diff --git a/images/export/track-all.png b/images/export/track-all.png new file mode 100644 index 0000000..075dd3d Binary files /dev/null and b/images/export/track-all.png differ diff --git a/images/export/untrack-all.png b/images/export/untrack-all.png new file mode 100644 index 0000000..860f221 Binary files /dev/null and b/images/export/untrack-all.png differ diff --git a/toc/docs.yml b/toc/docs.yml index 9fa03ea..14c8394 100644 --- a/toc/docs.yml +++ b/toc/docs.yml @@ -198,6 +198,8 @@ cats: title: Fine-tuning channels - id: adding-context title: Adding some context to channels + - id : pid-tracking + title: Tracking process IDs - id: saving-loading-tracing-session title: Saving and loading tracing session configurations - id: sending-trace-data-over-the-network