table of contents
LATRACE(1) | LATRACE(1) |
NAME¶
latrace - LD_AUDIT 2.4+ libc frontend
SYNOPSIS¶
latrace [-snltfvhiBdISbcCyYLpoaNADVTFERq] command [arg ... ]
DESCRIPTION¶
The latrace tracer is able to run a command and display its dynamic library calls using a LD_AUDIT libc feature, available from libc version 2.4 onward. It is also capable to measure and display various statistics of dynamic calls. See the section called “DISCUSSION” for more details.
If the header file with functions' declarations is provided, latrace will display functions’s arguments. The header file file syntax is similar to the C language, with several exceptions See the section called “HEADERS” for more details.
The latrace by default fully operates inside of the traced program. However another "pipe mode" is available to move the main work to the tracer - the latrace binary. See the section called “PIPE mode” for more details.
OPTIONS¶
-l, --libs lib1[,lib2,...]
-t, --libs-to lib1[,lib2,...]
-f, --libs-from lib1[,lib2,...]
-s, --sym sym1[,sym2,...]
-n, --sym-omit sym1[,sym2,...]
-L, --lib-subst s1[,s2,...]
-c, --counts
-C, --sort-counts stat
-p, --pipe
-N, --conf
-A, --enable-args
-D, --detail-args
-a, --args file
-y, --framesize number
-Y, --no-framesize-check
-F, --no-follow-fork
-E, --no-follow-exec
-S, --timestamp
-b, --flow-below sym1[,sym2,...]
-I, --no-indent-sym
-i, --indent-sym indent_size
-B, --braces
-d, --demangle
-T, --hide-tid
-o, --output file
-R, --ctl-config
-q, --disable
-v, --verbose
-V, --version
-h, --help
EXAMPLES¶
latrace cat
latrace -A cat
latrace -Ap cat
latrace -a latrace.conf cat
latrace -A -s read,write cat
latrace -b sysconf kill
latrace -Al libproc w
latrace -c ls
latrace -C time ls
latrace -o output.latrace ls
latrace -L krava1%krava2 ex
latrace -L krava1~libkrava2.so ex
latrace -L libkrava1.so=libkrava2.so ex
DISCUSSION¶
NAMES CHECK¶
For options "-l -t -f -s -n -b" the * symbol can be used to switch to the substring search. If it is not specified, the exact search for the name is done.
Examples:
-s "*krava" checks for symbols with "krava" substring.
-s "krava" checks only for "krava" symbol
LD_AUDIT¶
This is just a brief and vague description of the LD_AUDIT feature. For more information look to rtld-audit(7) man done by Petr Baudis or study the glibc/latrace source code. Very brief explanation follows.
The libc dynamic linker audit feature allows to trace/audit program’s symbols/libraries. The feature is enabled by the LD_AUDIT environment variable. This variable must contain path to the audit shared library. This audit library needs to follow specific interface. The interface functions will be then called by the dynamic linker appropriatelly.
The audit library needs to export following symbols (the "la_PLTENTER" and "la_PLTEXIT" names are architecture dependent).
"la_activity" "la_objsearch" "la_objopen" "la_preinit" "la_symbind32" "la_symbind64" "la_PLTENTER" "la_PLTEXIT" "la_objclose"
As for the latrace package the audit shared library is called libltaudit.so.
OBJSEARCH¶
The objsearch LD_AUDIT interface provide means for changing traced program shared object names/locations. The -L option argument should have following form:
-L s1[,s2,...] where sN is src [=%~] dst
The src is the source pattern/name and dst is the destination name/pattern.
= | Comparing src with the library name. If matched, replace the library name with dst. library name - /lib/krava1.so src - /lib/krava1.so dst - /lib/krava2.so final library name - /lib/krava2.so |
% | Looking for the src in the library name. If found, replace the src with dst part. library name - /lib/krava1.so src - krava1 dst - krava2 final library name - /lib/krava2.so |
~ | Looking for the src in the library name. If found, replace the library name with dst. library name - /lib/krava1.so src - krava1 dst - /lib/krava2.so final library name - /lib/krava2.so |
PIPE mode¶
The latrace can work in two modes. The first one native does does the output directly in the traced program process. The other one, pipe mode use the IPC fifo mechanism to send the data from the traced process to the latrace process. The latrace process is then responsible for the output. Using the pipe mode you loose the traced program standard output context with printed symbols.
By using the pipe mode, the latrace is not dependent on the trace program usage/manipulation of the standard output descriptor. Also the symbol statistics counts -c, -C options use the pipe mode to transfer symbol information to the latrace binary, and the latrace binary does the counts at the end.
CONFIG¶
The latrace provide possibility to enable/disable some of the options by means of configuration file. Some of the options are linked to the command line arguments some of them are not. When latrace starts the global configuration file is read. This file is usually being placed in here:
/etc/latrace.d/latrace.conf
Having default values read from this file, user can overload any of them by command line options or by supling another config file via -N, --conf option.
The configuration file syntax is roughly:
INCLUDE <anotherconfigfile> OPTIONS {
OPTION1 = VALUE
OPTION2 = YES|NO
...
OPTIONN = VALUE } # comment
Configuration file options
HEADERS = FILE
INDENT_SYM = VALUE
PIPE = BOOL
TIMESTAMP = BOOL
FRAMESIZE = VALUE
FRAMESIZE_CHECK = BOOL
HIDE_TID = BOOL
FOLLOW_FORK = BOOL
FOLLOW_EXEC = BOOL
DEMANGLE = BOOL
BRACES = BOOL
ENABLE_ARGS = BOOL
DETAIL_ARGS = BOOL
OUTPUT_TTY = FILE
LIBS = LIB1[,LIB2,...]
LIBS_TO = LIB1[,LIB2,...]
LIBS_FROM = LIB1[,LIB2,...]
SYM = SYM1[,SYM2,...]
SYM_OMIT = SYM1[,SYM2,...]
SYM_BELOW = SYM1[,SYM2,...]
SYM_NOEXIT = SYM1[,SYM2,...]
ARGS_STRING_POINTER_LENGTH = BOOL
HEADERS¶
The latrace header file allows user to define symbols as an classic C functions with arguments. Argument names will be displayed together with values as the latrace output. The more arguments are defined, the more performance and memory penalties should be expected.
The package is delivered with several predefined header files for the most commonly used functions. List of the glibc header files used follows (the list mostly follows the ltrace header files list, and author is willing to update it according to the needs)
ctype.h dirent.h dlfcn.h fcntl.h getopt.h inet.h ioctl.h libintl.h libio.h locale.h misc.h mman.h ncurses.h netdb.h pthread.h pwd.h resource.h signal.h socket.h stat.h stdio.h stdlib.h string.h syslog.h term.h termios.h time.h typedefs.h unistd.h utmp.h wait.h
The latrace header files are usually stored under directory:
/etc/latrace.d/headers/
User can specify single header file using command line option or configuration file. This file then can include other needed headers. As already mentioned, the latrace config file syntax lightly follows the C language syntax. Following part describes the latrace config file language.
void char u_char short u_short int u_int long u_long llong u_llong # (long long) float double
typedef base_type new_type; typedef base_type * new_type; typedef base_type ** new_type;
/\* comments \*/
#include "filename"
START:: struct NAME { STRUCT_DEF }; STRUCT_DEF:: DEF | EMPTY DEF:: NAME NAME |
NAME '*' NAME |
struct NAME NAME |
struct NAME '*' NAME NAME:: [-0-9a-zA-Z_]+
START:: DEF '(' ARGS ')' ';' ARGS:: ARGS ',' DEF | DEF | EMPTY
START:: ENUM NAME '{' ENUM_DEF '}' ';' ENUM_DEF:: ENUM_DEF ',' ENUM_ELEM | ENUM_ELEM ENUM_ELEM:: NAME '=' NAME | NAME
---[ cut here ]----------------------------- enum krava {
krava1 = 1,
krava2,
krava3 = 100 }; #include "krava.conf" typedef u_int pid_t; struct ex_st {
pid_t p;
int cnt;
char *name; }; int f1(pid_t p, struct ex_st *k); int f2(char* name, struct ex_st k, int k = krava); struct ex_st* f3(pid_t *p, struct ex_st k); ---[ cut here ]-----------------------------
PORTS¶
The latrace should work on any glibc system with LD_AUDIT support. However arguments details are architecture specific and need special support inside latrace itself.
Author is willing to port the latrace to any architecture, as long as he got an access to corresponding system. Currently functional ports are:
x86 | ok |
x86_64 | ok |
arm | ok |
BUGS¶
MANY, plz report bugs to <latrace@lists.fedorahosted.org[1]> or <olsajiri@gmail.com[2]>.
You can also visit the http://people.redhat.com/jolsa/latrace/ page to see the latest release notes information.
LD_AUDIT related glibc bugs:
AUTHOR¶
Jiri Olsa <olsajiri@gmail.com[2]>
CONTRIBUTORS¶
LICENSE¶
This is free software, distributed under the GPLv3 license.
SEE ALSO¶
AUTHOR¶
Jiri Olsa <olsajiri@gmail.com>
NOTES¶
- 1.
- latrace@lists.fedorahosted.org
- 2.
- olsajiri@gmail.com
- 3.
- nix@esperi.org.uk
- 4.
- akos.pasztory@gmail.com
- 5.
- art.08.09@gmail.com
- 6.
- david.gilbert@linaro.org
- 7.
- sping@gentoo.org
07/01/2024 | 0.5.11 |