Add snapshot howto

Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 8edb6dc1e6e63817728960f6ee335a6dfe46a3f9..f57abf42a66f102aa506e94a046d89ad8d751769 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,6 +1,6 @@
 SUBDIRS = man
 EXTRA_DIST = quickstart.txt streaming-howto.txt python-howto.txt \
-             calibrate.txt kernel-CodingStyle.txt
+       snapshot-howto.txt calibrate.txt kernel-CodingStyle.txt
 
 dist_doc_DATA = quickstart.txt streaming-howto.txt python-howto.txt \
-                               calibrate.txt
+       snapshot-howto.txt calibrate.txt

diff --git a/doc/snapshot-howto.txt b/doc/snapshot-howto.txt
new file mode 100644 (file)
index 0000000..a0bb212
--- /dev/null
+++ b/doc/snapshot-howto.txt
@@ -0,0 +1,88 @@
+LTTng Flight Recorder Snapshot HOWTO
+
+Mathieu Desnoyers
+July 21st, 2013
+
+This document presents how to use the snapshot feature of LTTng.
+
+Snapshots allow to grab the content of flight recorder tracing buffers
+at the time the snapshot record command is invoked. Flight recorder
+tracing gather trace data in memory, overwriting the oldest information,
+without requiring any disk I/O. The snapshot record command exports the
+snapshot to the destination specified by the user.
+
+Basic usage:
+
+Session daemon started as root for kernel tracing:
+
+# lttng-sessiond -d
+
+From a user part of the tracing group (for kernel tracing):
+
+$ lttng create --snapshot
+$ lttng enable-event -k -a      # enable kernel tracing
+$ lttng enable-event -u -a      # enable user-space tracing
+$ lttng start
+
+    [ do something, generate activity on the system ]
+
+$ lttng snapshot record
+
+    [ do more stuff... ]
+
+$ lttng snapshot record
+
+$ lttng stop
+$ lttng destroy
+
+Each "lttng snapshot" command records a snapshot of the current buffer
+state. "lttng enable --snapshot" automatically setups the buffers in
+overwrite mode for flight recording, and does not attach any output file
+to the trace. The "lttng snapshot record" command can be performed
+either while tracing is started or stopped.
+
+As an example, this generates the following hierarchy under the
+directory reported by the "create" command above:
+
+.
+├── snapshot-1-20130721-141838-0
+│   ├── kernel
+│   │   ├── channel0_0
+│   │   ├── channel0_1
+│   │   ├── channel0_2
+│   │   ├── channel0_3
+│   │   └── metadata
+│   └── ust
+│       └── uid
+│           └── 1000
+│               └── 64-bit
+│                   ├── channel0_0
+│                   ├── channel0_1
+│                   ├── channel0_2
+│                   ├── channel0_3
+│                   └── metadata
+└── snapshot-1-20130721-141842-1
+    ├── kernel
+    │   ├── channel0_0
+    │   ├── channel0_1
+    │   ├── channel0_2
+    │   ├── channel0_3
+    │   └── metadata
+    └── ust
+        └── uid
+            └── 1000
+                └── 64-bit
+                    ├── channel0_0
+                    ├── channel0_1
+                    ├── channel0_2
+                    ├── channel0_3
+                    └── metadata
+
+
+Then, running babeltrace on, e.g. here
+
+babeltrace snapshot-1-20130721-141838-0
+
+shows the content of the first snapshot.
+
+Please refer to the lttng(1) manpage for details on the snapshot mode.