-
Notifications
You must be signed in to change notification settings - Fork 15
/
README
87 lines (68 loc) · 3.74 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
--------------------------------------------------------------------------------
DESCRIPTION
tbstack -- fast stack trace utility.
A primary design goal is to minimize performance impact on a process to
make it possible to run it in low-latency systems. It is achieved by
copying contents of stack regions when the process is frozen and unwinding
stack when the process continues working. The idea was inspired by perf
tool.
The program uses POSIX, Linux API, and libunwind.
--------------------------------------------------------------------------------
COMPATIBILITY
This utility is intended for use with Linux on ARM, x86, and x86_64.
Libraries: libelf, libunwind. It is recommended to get the latest version of
libunwind.
--------------------------------------------------------------------------------
INSTALLATION
The build system is autotools:
$ ./autogen.sh # Only required if building from git
$ ./configure
$ make
# make install
Configure options are available:
$ ./configure --disable-ptrace
$ make DESTDIR=/opt/tbstack
DESTDIR tbstack binary will be installed there
--disable-ptrace disable support for libunwind-ptrace
--------------------------------------------------------------------------------
USAGE
usage: tbstack <pid>
tbstack <pid>/<tid1>,...,<tidn>
tbstack <pid>/RS
options: --help show this
--ignore-deleted try to open shared objects marked as deleted
--use-waitpid-timeout set alarm to interrupt waitpid
--proc-mem prefer reading /proc/pid/mem. default flavor
is process_vm_readv
--ptrace use libunwind-ptrace interface (slower)
--show-rsp show %rsp in second column
--show-state show thread states
--stack-size <size> maximum stack size to copy (default is current
RLIMIT_STACK)
--stop-timeout timeout for waiting the process to freeze, in
milliseconds. default value is 1000
--verbose verbose error messages
--version output version information and exit
--------------------------------------------------------------------------------
HOW IT WORKS
Binaries in mainstream Linux distributions are built with frame pointers
omitted, so stack unwinding becomes more complex than just traversing a linked
list. In order to move to the next frame we have to find corresponding
frame description entry (FDE) in .eh_frame ELF section. It imples at least two
binary searches: for a binary or shared object containing the code, and the
FDE.
One of solutions is examining process memory by ptrace and resolving next
frame addresses while the process is stopped. Libunwind-ptrace implements such
approach. Tbstack supports this interface as a flavor which can be enabled by
--ptrace command line argument.
In order to minimize performance impact tbstack uses another approach. At first
it examines process' memory layout reading /proc/pid/maps. When the process is
frozen (PTRACE_ATTACH to the main thread + SIGSTOP to start freezing other
threads) it copies all threads' general-purpose registers and contents of stack
from %rsp to end of memory region or up to maximum stack size if specified
with --stack-size argument. System call proc_vm_readv is used. If it is not
supported, the program falls back to reading /proc/pid/mem. The process
continues execution. The collected data is enough to trace stacks. It is
arranged in structures snapshot and mem_map and can be accessed through callback
routines passed to libunwind by unw_create_addr_space (see
http://www.nongnu.org/libunwind/man/unw_create_addr_space(3).html).