Merge branch 'master' into memleak-finder

[lttng-tools.git] / extras / core-handler / README

diff --git a/extras/core-handler/README b/extras/core-handler/README
new file mode 100644 (file)
index 0000000..039ce3b
--- /dev/null
+++ b/extras/core-handler/README
@@ -0,0 +1,78 @@
+LTTng core dump snapshot handler
+Christian Babeux, June 2013
+
+This is a custom core dump program that will be called when a core dump
+occurs. The program will save the core data in CORE_PATH and also, if a
+root session daemon is running, will record a snapshot of tracing data
+using the lttng command line utility.
+
+The core dump snapshot handler can be installed by using the provided
+install.sh script or by adding the appropriate program pipe line to
+/proc/sys/kernel/core_pattern. Refer to core(5) for more information
+about the Linux kernel core dump handling and custom handler mechanism.
+
+Installation:
+
+# ./install.sh
+Backup current core_pattern in core_pattern.bkp.
+Successfully installed core_pattern.
+
+How to use:
+
+You can use the provided test.sh script to test that the core dump snapshot
+handler is working properly:
+
+# ./test.sh
+Setup coredump-handler...
+Session coredump-handler created.
+Default snapshot output set to: /tmp/lttng/snapshot
+Snapshot mode set. Every channel enabled for that session will be set in overwrite mode and mmap output
+kernel event sched_switch created in channel channel0
+Tracing started for session coredump-handler
+Sleeping...
+Crashing...
+Segmentation fault (core dumped)
+Sleeping...
+Waiting for data availability
+Tracing stopped for session coredump-handler
+Session coredump-handler destroyed
+Core dump will be available in /tmp/lttng/core.
+Snapshot will be available in /tmp/lttng/snapshot.
+
+# tree /tmp/lttng
+/tmp/lttng
+├── core
+│   └── core.29085
+└── snapshot
+    └── snapshot-1-20130719-175041-0
+        └── kernel
+            ├── channel0_0
+            ├── channel0_1
+            ├── channel0_2
+            ├── channel0_3
+            └── metadata
+
+Chaining with other core dump handler:
+
+Some Linux distributions already use their own core dump handler
+(such as systemd 'systemd-coredump' utility). It is possible to chain these
+core dump utility with the core dump snapshot handler. In order to achieve
+this, the core dump snapshot handler must be first in the chain (e.g.
+installed in /proc/sys/kernel/core_pattern) and the other core dump
+handler must be called from within the core dump snapshot handler script.
+
+Example (chaining with systemd systemd-coredump):
+
+# cat /proc/sys/kernel/core_pattern
+|/path/to/lttng/handler.sh %p %u %g %s %t %h %e %E %c
+
+In LTTng handler.sh script:
+
+[...]
+# Save core dump from stdin.
+#$MKDIR_BIN -p "${CORE_PATH}"
+#$CAT_BIN - > "${CORE_PATH}/${CORE_PREFIX}.$p"
+
+# Optional, chain core dump handler with original systemd script.
+$CAT_BIN - | /usr/lib/systemd/systemd-coredump $p $u $g $s $t $e
+[...]