Add core dump snapshot handler script
[lttng-tools.git] / extras / core-handler / README
1 LTTng core dump snapshot handler
2 Christian Babeux, June 2013
3
4 This is a custom core dump program that will be called when a core dump
5 occurs. The program will save the core data in CORE_PATH and also, if a
6 root session daemon is running, will record a snapshot of tracing data
7 using the lttng command line utility.
8
9 The core dump snapshot handler can be installed by using the provided
10 install.sh script or by adding the appropriate program pipe line to
11 /proc/sys/kernel/core_pattern. Refer to core(5) for more information
12 about the Linux kernel core dump handling and custom handler mechanism.
13
14 Installation:
15
16 # ./install.sh
17 Backup current core_pattern in core_pattern.bkp.
18 Successfully installed core_pattern.
19
20 How to use:
21
22 You can use the provided test.sh script to test that the core dump snapshot
23 handler is working properly:
24
25 # ./test.sh
26 Setup...
27 Spawning a session daemon
28 Session auto-20130626-224838 created.
29 Kernel channel chan enabled for session auto-20130626-224838
30 kernel event sched_switch created in channel chan
31 Tracing started for session auto-20130626-224838
32 Sleeping...
33 Crashing...
34 ./test.sh: line 35: 16980 Segmentation fault (core dumped)
35 $(dirname $0)/crash
36 Waiting for data availability
37 Tracing stopped for session auto-20130626-224838
38 Session auto-20130626-224838 destroyed
39 Core dump and snapshot will be available in /tmp/lttng/{core,snapshot}.
40
41 # tree /tmp/lttng
42 /tmp/lttng
43 |-- core
44 | `-- core.16980
45 `-- snapshot
46 `-- snapshot
47 |-- chan_0
48 |-- chan_1
49 |-- chan_2
50 |-- chan_3
51 |-- chan_4
52 |-- chan_5
53 |-- chan_6
54 |-- chan_7
55 `-- metadata
56
57 Chaining with other core dump handler:
58
59 Some Linux distributions already use their own core dump handler
60 (such as systemd 'systemd-coredump' utility). It is possible to chain these
61 core dump utility with the core dump snapshot handler. In order to achieve
62 this, the core dump snapshot handler must be first in the chain (e.g.
63 installed in /proc/sys/kernel/core_pattern) and the other core dump
64 handler must be called from within the core dump snapshot handler script.
65
66 Example (chaining with systemd systemd-coredump):
67
68 # cat /proc/sys/kernel/core_pattern
69 |/path/to/lttng/handler.sh %p %u %g %s %t %h %e %E %c
70
71 In LTTng handler.sh script:
72
73 [...]
74 # Save core dump from stdin.
75 $MKDIR_BIN -p "${CORE_PATH}"
76
77 # Optional, chain core dump handler with original systemd script.
78 $CAT_BIN - | /usr/lib/systemd/systemd-coredump $p $u $g $s $t $e
79 [...]
This page took 0.04086 seconds and 4 git commands to generate.