man/warning::debuginfo.7stap

   1 .\" t
   2 .TH WARNING::DEBUGINFO 7stap
   3 .SH NAME
   4 warning::debuginfo \- systemtap missing-debuginfo warnings
   5
   6 .\" macros
   7 .de SAMPLE
   8
   9 .nr oldin \\n(.i
  10 .br
  11 .RS
  12 .nf
  13 .nh
  14 ..
  15 .de ESAMPLE
  16 .hy
  17 .fi
  18 .RE
  19 .in \\n[oldin]u
  20
  21 ..
  22
  23 .SH DESCRIPTION
  24 For many symbolic probing operations, systemtap needs DWARF debuginfo for
  25 the relevant binaries.  This often includes resolving function/statement
  26 probes, or $context variables in related handlers.  DWARF debuginfo may
  27 be found in the original binaries built during compilation, or may have
  28 been split into separate files.  The
  29 .IR SYSTEMTAP_DEBUGINFO_PATH
  30 environment variable affects where systemtap looks for these files.
  31 .PP
  32 If your operating system came from a distributor, check with them if
  33 debuginfo packages or variants are available.  If your distributor does
  34 not have debuginfo-equipped binaries at all, you may need to rebuild it.
  35 .PP
  36 Systemtap uses the
  37 .IR elfutils
  38 library to process ELF/DWARF files.  The version of elfutils used by systemtap
  39 is the number after the slash in the
  40 .IR \-V
  41 output:
  42 .SAMPLE
  43 % stap -V
  44 Systemtap translator/driver (version 2.3/0.156, rpm 2.3-1.fc19)
  45 Copyright (C) 2005-2014 Red Hat, Inc. and others
  46 [...]
  47 .ESAMPLE
  48 This indicates systemtap version 2.3 with elfutils version 0.156.
  49
  50 .TP
  51 kernel debuginfo
  52 For scripts that target the kernel, systemtap may search for the
  53 .IR vmlinux
  54 file created during its original build.  This is distinct from the
  55 boot-loader's compressed/stripped
  56 .IR vmlinuz
  57 file, and much larger.  If you have a hand-built kernel, make sure
  58 it was built with the
  59 .IR CONFIG_DEBUG_INFO=y
  60 option.
  61
  62 .TP
  63 process debuginfo
  64 For scripts that target user-space, systemtap may search for debuginfo.
  65 If you have hand-built binaries, use
  66 .IR "CFLAGS=-g -O2"
  67 to compile them.
  68
  69 .TP
  70 minidebuginfo
  71 On some systems, binaries may be compiled with a subset of debuginfo
  72 useful for function tracing and backtraces.  This 'Minidebuginfo' is
  73 a xz compressed section labeled .gnu_debugdata.  Support for
  74 minidebuginfo relies on elfutils version 0.156 or later.
  75
  76 .TP
  77 compressed debuginfo
  78 On some systems, debuginfo may be available, but compressed into
  79 .IR .zdebug_*
  80 sections.  Support for compressed debuginfo relies on elfutils
  81 version 0.153 or later.
  82
  83 .TP
  84 unnecessary debuginfo
  85 In some cases, a script may be altered to avoid requiring debuginfo.
  86 For example, as script that uses
  87 .IR "probe syscall.*"
  88 probes could try instead
  89 .IR "probe nd_syscall.*"
  90 (for non-DWARF syscall): these work similarly, and use more intricate
  91 (fragile) tapset functions to extract system call arguments.  Another
  92 option is use of compiled-in instrumentation such as kernel tracepoints
  93 or user-space
  94 .IR <sys/sdt.h>
  95 markers in libraries or executables, which do not require debuginfo.
  96 If debuginfo was required for resolving a complicated
  97 .IR $var->foo->bar
  98 expression, it may be possible to use
  99 .IR @cast(var,"foo","foo.h")->foo->bar
 100 to synthesize debuginfo for that type from a header file.
 101
 102 .SH AUTOMATION
 103
 104 On some platforms, systemtap may advise what commands to run, in order
 105 to download needed debuginfo.  Another possibility is to invoke systemtap
 106 with the
 107 .IR \-\-download\-debuginfo
 108 flag.
 109 The
 110 .IR stap-prep
 111 script included with systemtap may be able to download the
 112 appropriate kernel debuginfo.  Another possibility is to install and
 113 use a
 114 .IR stap\-server
 115 remote-compilation instance on a machine on your network, where
 116 debuginfo and compilation resources can be centralized.  Try the
 117 .IR "stap --use-server"
 118 option, in case such a server is already running.
 119
 120 .SH SEE ALSO
 121 .nh
 122 .nf
 123 .IR stap (1),
 124 .IR stappaths (7),
 125 .IR stap-server (8),
 126 .IR stap-prep (1),
 127 .IR strip (1),
 128 .IR error::dwarf (7stap),
 129 .IR error::reporting (7stap),
 130 .IR error::contextvars (7stap),
 131 .IR http://fedorahosted.org/elfutils ,
 132 .IR http://fedoraproject.org/wiki/Features/MiniDebugInfo