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 dependencies:

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)                    pylint3 python3 python3-protobuf

29) ```
30) 

31) For the graphical user interface, install the additional dependencies:
32) 
33) ```
34) apt-get install -y glade libglib2.0-dev libgtk-3-dev python3-gi
35) ```
36) 

37) Change to the directory of this `REAMDE.md` file.
38) 
39) Configure a build directory:
40) 
41) ```
42) mkdir build
43) cd build
44) cmake -G Ninja -D CMAKE_BUILD_TYPE=Release ..
45) ```
46) 
47) Build:
48) 
49) ```
50) ninja
51) ```
52) 
53) Run tests:
54) 
55) ```
56) ctest
57) ```
58) 

59) Set up for direct usage from build directory (to be done in each shell):
60) 
61) ```
62) source exports
63) ```
64) 

65) ## Tracing Applications
66) 
67) To trace an application, prefix the command with `upt-trace` and the
68) file name for the trace.  For example, to trace the command
69) ```
70) /usr/bin/printf "trace me"
71) ```
72) run the following command:
73) ```

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

75) ```
76) 
77) To show the recorded events, run:
78) ```

79) upt-tool mytrace.proto dump
80) ```
81) 
82) ## Graphical User interface
83) 
84) To explore a trace in the graphical user interface, run:
85) ```
86) <build dir>/upt-gui/upt-gui.py mytrace.proto

87) ```
88) 
89) ## Example: Trace Build Process
90) 
91) To show the capabilities of the UProcTrace, a process that calls several child
92) processes is required. In this example, the build of UProcTrace is used for
93) this purpose.
94) 
95) Change to the build directory.
96) 
97) Start a new shell to be traced:

98) 

99) ```

100) upt-trace mytrace.proto bash

101) ```
102) 
103) Configure another build directory for this tracing example and run the build:
104) 
105) ```
106) mkdir example_trace_build
107) cd example_trace_build
108) cmake -G Ninja -D CMAKE_BUILD_TYPE=Release ../..
109) ninja
110) ```
111) 
112) Stop tracing by ending the shell:
113) 
114) ```
115) exit
116) ```
117) 
118) Show traced information:

119) 

120) ```

121) upt-tool mytrace.proto dump

122) ```
123)