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 coredump-handler...
  27 Session coredump-handler created.
  28 Default snapshot output set to: /tmp/lttng/snapshot
  29 Snapshot mode set. Every channel enabled for that session will be set in overwrite mode and mmap output
  30 kernel event sched_switch created in channel channel0
  31 Tracing started for session coredump-handler
  32 Sleeping...
  33 Crashing...
  34 Segmentation fault (core dumped)
  35 Sleeping...
  36 Waiting for data availability
  37 Tracing stopped for session coredump-handler
  38 Session coredump-handler destroyed
  39 Core dump will be available in /tmp/lttng/core.
  40 Snapshot will be available in /tmp/lttng/snapshot.
  41
  42 # tree /tmp/lttng
  43 /tmp/lttng
  44 ├── core
  45 │   └── core.29085
  46 └── snapshot
  47     └── snapshot-1-20130719-175041-0
  48         └── kernel
  49             ├── channel0_0
  50             ├── channel0_1
  51             ├── channel0_2
  52             ├── channel0_3
  53             └── metadata
  54
  55 Chaining with other core dump handler:
  56
  57 Some Linux distributions already use their own core dump handler
  58 (such as systemd 'systemd-coredump' utility). It is possible to chain these
  59 core dump utility with the core dump snapshot handler. In order to achieve
  60 this, the core dump snapshot handler must be first in the chain (e.g.
  61 installed in /proc/sys/kernel/core_pattern) and the other core dump
  62 handler must be called from within the core dump snapshot handler script.
  63
  64 Example (chaining with systemd systemd-coredump):
  65
  66 # cat /proc/sys/kernel/core_pattern
  67 |/path/to/lttng/handler.sh %p %u %g %s %t %h %e %E %c
  68
  69 In LTTng handler.sh script:
  70
  71 [...]
  72 # Save core dump from stdin.
  73 #$MKDIR_BIN -p "${CORE_PATH}"
  74 #$CAT_BIN - > "${CORE_PATH}/${CORE_PREFIX}.$p"
  75
  76 # Optional, chain core dump handler with original systemd script.
  77 $CAT_BIN - | /usr/lib/systemd/systemd-coredump $p $u $g $s $t $e
  78 [...]