| 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 is |
| 27 |
created by the compiler when using \fICFLAGS \-g\fP, and may |
| 28 |
be found in the original binaries built during compilation, or may have |
| 29 |
been split into separate files. The |
| 30 |
.IR SYSTEMTAP_DEBUGINFO_PATH |
| 31 |
environment variable affects where systemtap looks for these files. |
| 32 |
.PP |
| 33 |
If your operating system came from a distributor, check with them if |
| 34 |
debuginfo packages or variants are available. If your distributor does |
| 35 |
not have debuginfo-equipped binaries at all, you may need to rebuild it. |
| 36 |
.PP |
| 37 |
Systemtap uses the |
| 38 |
.IR elfutils |
| 39 |
library to process ELF/DWARF files. The version of elfutils used by systemtap |
| 40 |
is the number after the slash in the |
| 41 |
.IR \-V |
| 42 |
output: |
| 43 |
.SAMPLE |
| 44 |
% stap -V |
| 45 |
Systemtap translator/driver (version 4.2/0.178, rpm 4.2-1.fc30) |
| 46 |
Copyright (C) 2005-2019 Red Hat, Inc. and others |
| 47 |
[...] |
| 48 |
.ESAMPLE |
| 49 |
This indicates systemtap version 4.2 with elfutils version 0.178. |
| 50 |
|
| 51 |
New enough versions of elfutils (0.178+) enable systemtap to automatically |
| 52 |
download correct debuginfo from servers run by you, your organization, |
| 53 |
and/or someone on the public internet. Try: |
| 54 |
.SAMPLE |
| 55 |
% export DEBUGINFOD_URLS=https://debuginfod.elfutils.org/ |
| 56 |
% export DEBUGINFOD_PROGRESS=1 # for progress messages, if you like |
| 57 |
.ESAMPLE |
| 58 |
and rerun systemtap. It might just work. If it doesn't, read on. |
| 59 |
|
| 60 |
.TP |
| 61 |
kernel debuginfo |
| 62 |
For scripts that target the kernel, systemtap may search for the |
| 63 |
.IR vmlinux |
| 64 |
file created during its original build. This is distinct from the |
| 65 |
boot-loader's compressed/stripped |
| 66 |
.IR vmlinuz |
| 67 |
file, and much larger. If you have a hand-built kernel, make sure |
| 68 |
it was built with the |
| 69 |
.IR CONFIG_DEBUG_INFO=y |
| 70 |
option. Some Linux distributions may include several kernel variants, |
| 71 |
including a confusingly named \fIkernel-debug\fR (an alternative kernel, |
| 72 |
with its own \fIkernel-debug-debuginfo\fR package), which is not the same |
| 73 |
thing as the \fIkernel-debuginfo\fR (DWARF data for the base \fIkernel\fR). |
| 74 |
The |
| 75 |
.IR stap\-prep |
| 76 |
program can help install the right set. |
| 77 |
|
| 78 |
.TP |
| 79 |
process debuginfo |
| 80 |
For scripts that target user-space, systemtap may search for debuginfo. |
| 81 |
If you have hand-built binaries, use |
| 82 |
.IR "CFLAGS=-g -O2" |
| 83 |
to compile them. |
| 84 |
|
| 85 |
.TP |
| 86 |
minidebuginfo |
| 87 |
On some systems, binaries may be compiled with a subset of debuginfo |
| 88 |
useful for function tracing and backtraces. This 'Minidebuginfo' is |
| 89 |
a xz compressed section labeled .gnu_debugdata. Support for |
| 90 |
minidebuginfo relies on elfutils version 0.156 or later. |
| 91 |
|
| 92 |
.TP |
| 93 |
compressed debuginfo |
| 94 |
On some systems, debuginfo may be available, but compressed into |
| 95 |
.IR .zdebug_* |
| 96 |
sections. Support for compressed debuginfo relies on elfutils |
| 97 |
version 0.153 or later. |
| 98 |
|
| 99 |
.TP |
| 100 |
unnecessary debuginfo |
| 101 |
In some cases, a script may be altered to avoid requiring debuginfo. |
| 102 |
For example, as script that uses |
| 103 |
.IR "probe syscall.*" |
| 104 |
probes could try instead |
| 105 |
.IR "probe nd_syscall.*" |
| 106 |
(for non-DWARF syscall): these work similarly, and use more intricate |
| 107 |
(fragile) tapset functions to extract system call arguments. Another |
| 108 |
option is use of compiled-in instrumentation such as kernel tracepoints |
| 109 |
or user-space |
| 110 |
.IR <sys/sdt.h> |
| 111 |
markers in libraries or executables, which do not require debuginfo. |
| 112 |
If debuginfo was required for resolving a complicated |
| 113 |
.IR $var->foo->bar |
| 114 |
expression, it may be possible to use |
| 115 |
.IR @cast(var,"foo","foo.h")->foo->bar |
| 116 |
to synthesize debuginfo for that type from a header file. |
| 117 |
|
| 118 |
.SH OTHER AUTOMATION |
| 119 |
|
| 120 |
On some platforms, systemtap may advise what commands to run, in order |
| 121 |
to download needed debuginfo. Another possibility is to invoke systemtap |
| 122 |
with the |
| 123 |
.IR \-\-download\-debuginfo |
| 124 |
flag, which uses ABRT. |
| 125 |
The |
| 126 |
.IR stap\-prep |
| 127 |
script included with systemtap may be able to download the |
| 128 |
appropriate kernel debuginfo. Another possibility is to install and |
| 129 |
use a |
| 130 |
.IR stap\-server |
| 131 |
remote-compilation instance on a machine on your network, where |
| 132 |
debuginfo and compilation resources can be centralized. Try the |
| 133 |
.IR "stap --use-server" |
| 134 |
option, in case such a server is already running. |
| 135 |
|
| 136 |
.SH SEE ALSO |
| 137 |
.nh |
| 138 |
.nf |
| 139 |
.IR gcc (1), |
| 140 |
.IR stap (1), |
| 141 |
.IR stappaths (7), |
| 142 |
.IR stap-server (8), |
| 143 |
.IR stap-prep (1), |
| 144 |
.IR strip (1), |
| 145 |
.IR warning::symbols (7stap), |
| 146 |
.IR error::dwarf (7stap), |
| 147 |
.IR error::reporting (7stap), |
| 148 |
.IR error::contextvars (7stap), |
| 149 |
.IR debuginfod (8), |
| 150 |
.IR http://elfutils.org/ , |
| 151 |
.IR https://sourceware.org/elfutils/Debuginfod.html , |
| 152 |
.IR http://fedoraproject.org/wiki/Features/MiniDebugInfo |