uproctrace

1) # UProcTrace: User-space Process Tracing
2) 
3) UProcTrace traces process executions and process ends on Linux systems.
4) 
5) On process starts, UProcTrace records the time, the entire command line,
6) working directory and environment. On process end, it logs the CPU time used by
7) the process (split by user and kernel time) and the peak memory usage.
8) 
9) UProcTrace is implemented in user-space, so does not reuire any special kernel
10) modules.  This means it can also be used in containers (e.g. docker) without
11) any changes the to conteiner host.  The implementation is based on the
12) `LD_PRELOAD` mechanism.  A shared library is injected into each process
13) started. This libarary records trace events at begin of the process (when the
14) preload library is initialized) and at the end of the process (when the library
15) is de-initiazlied).
16) 
17) ## Building
18) 
19) UProcTrace is developed on Debian Linux 10 "buster".
20) 
21) Install the prerequisites:
22) 
23) ```
24) apt-get install -y build-essential cmake gcc \
25)                    libprotobuf-c-dev libprotobuf-dev
26)                    ninja-build \
27)                    protobuf-c-compiler protobuf-compiler \
28)                    python3 python3-protobuf
29) ```
30) 
31) Change to the directory of this `REAMDE.md` file.
32) 
33) Configure a build directory:
34) 
35) ```
36) mkdir build
37) cd build
38) cmake -G Ninja -D CMAKE_BUILD_TYPE=Release ..
39) ```
40) 
41) Build:
42) 
43) ```
44) ninja
45) ```
46) 
47) Run tests:
48) 
49) ```
50) ctest
51) ```
52) 

53) Set up for direct usage from build directory (to be done in each shell):
54) 
55) ```
56) source exports
57) ```
58) 

59) ## Tracing Applications
60) 
61) To trace an application, prefix the command with `upt-trace` and the
62) file name for the trace.  For example, to trace the command
63) ```
64) /usr/bin/printf "trace me"
65) ```
66) run the following command:
67) ```

68) upt-trace mytrace.proto /usr/bin/printf "trace me"

69) ```
70) 
71) To show the recorded events, run:
72) ```

73) upt-dump mytrace.proto

74) ```
75) 
76) ## Example: Trace Build Process
77) 
78) To show the capabilities of the UProcTrace, a process that calls several child
79) processes is required. In this example, the build of UProcTrace is used for
80) this purpose.
81) 
82) Change to the build directory.
83) 
84) Start a new shell to be traced:
85) ```

86) upt-trace mytrace.proto bash

87) ```
88) 
89) Configure another build directory for this tracing example and run the build:
90) 
91) ```
92) mkdir example_trace_build
93) cd example_trace_build
94) cmake -G Ninja -D CMAKE_BUILD_TYPE=Release ../..
95) ninja
96) ```
97) 
98) Stop tracing by ending the shell:
99) 
100) ```
101) exit
102) ```
103) 
104) Show traced information:
105) ```

106) upt-dump mytrace.proto