Debian Codegraph @

man/warning::debuginfo.7stap

raw
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