Add core dump snapshot handler script

[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..4482fd1
--- /dev/null
+++ b/extras/core-handler/README
@@ -0,0 +1,79 @@
+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...
+Spawning a session daemon
+Session auto-20130626-224838 created.
+Kernel channel chan enabled for session auto-20130626-224838
+kernel event sched_switch created in channel chan
+Tracing started for session auto-20130626-224838
+Sleeping...
+Crashing...
+./test.sh: line 35: 16980 Segmentation fault      (core dumped)
+$(dirname $0)/crash
+Waiting for data availability
+Tracing stopped for session auto-20130626-224838
+Session auto-20130626-224838 destroyed
+Core dump and snapshot will be available in /tmp/lttng/{core,snapshot}.
+
+# tree /tmp/lttng
+/tmp/lttng
+|-- core
+|   `-- core.16980
+`-- snapshot
+    `-- snapshot
+        |-- chan_0
+        |-- chan_1
+        |-- chan_2
+        |-- chan_3
+        |-- chan_4
+        |-- chan_5
+        |-- chan_6
+        |-- chan_7
+        `-- 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}"
+
+# Optional, chain core dump handler with original systemd script.
+$CAT_BIN - | /usr/lib/systemd/systemd-coredump $p $u $g $s $t $e
+[...]