--------------------------------------------------------------------------------
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
https://www.nongnu.org/libunwind/man/unw_create_addr_space(3).html).