--------------------------------------------------------------------------------
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 x86_64.

Libraries: libelf, libunwind. It is recommended to get the latest version of
libunwind.

--------------------------------------------------------------------------------
INSTALLATION

In simple case you only need to run make:

    $ make
    # make install

Other options are available:

    $ make LIBUNWIND_DIR=/opt/libunwind BINDIR=/opt/tbstack/bin \
        NO_LIBUNWIND_PTRACE=1

    LIBUNWIND_DIR          libunwind installation prefix.
    BINDIR                 tbstack binary will be installed there.
    NO_LIBUNWIND_PTRACE    1 to disable support for libunwind-ptrace.

--------------------------------------------------------------------------------
USAGE

usage:    tbstack <pid>
          tbstack <pid>/<tid1>,...,<tidn>

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 on systems
                                with kernel older than 3.2. on modern kernels
                                default flavor is process_vm_readv)
          --ptrace              use libunwind-ptrace interface (slower)
          --show-rsp            show %rsp in second column
          --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

--------------------------------------------------------------------------------
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 on kernels from
version 3.2, on older kernels data is read from /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).