uproctrace

@@ -8,4 +8,5 @@ enable_testing()

 add_subdirectory(dump)

 add_subdirectory(libuptev)

 add_subdirectory(libuptpl)

+add_subdirectory(upt-trace)

 add_subdirectory(tests)

@@ -0,0 +1,102 @@

+# UProcTrace: User-space Process Tracing

+

+UProcTrace traces process executions and process ends on Linux systems.

+

+On process starts, UProcTrace records the time, the entire command line,

+working directory and environment. On process end, it logs the CPU time used by

+the process (split by user and kernel time) and the peak memory usage.

+

+UProcTrace is implemented in user-space, so does not reuire any special kernel

+modules.  This means it can also be used in containers (e.g. docker) without

+any changes the to conteiner host.  The implementation is based on the

+`LD_PRELOAD` mechanism.  A shared library is injected into each process

+started. This libarary records trace events at begin of the process (when the

+preload library is initialized) and at the end of the process (when the library

+is de-initiazlied).

+

+## Building

+

+UProcTrace is developed on Debian Linux 10 "buster".

+

+Install the prerequisites:

+

+```

+apt-get install -y build-essential cmake gcc \

+                   libprotobuf-c-dev libprotobuf-dev

+                   ninja-build \

+                   protobuf-c-compiler protobuf-compiler \

+                   python3 python3-protobuf

+```

+

+Change to the directory of this `REAMDE.md` file.

+

+Configure a build directory:

+

+```

+mkdir build

+cd build

+cmake -G Ninja -D CMAKE_BUILD_TYPE=Release ..

+```

+

+Build:

+

+```

+ninja

+```

+

+Run tests:

+

+```

+ctest

+```

+

+## Tracing Applications

+

+To trace an application, prefix the command with `upt-trace` and the

+file name for the trace.  For example, to trace the command

+```

+/usr/bin/printf "trace me"

+```

+run the following command:

+```

+<build dir>/bin/upt-trace mytrace.proto /usr/bin/printf "trace me"

+```

+

+To show the recorded events, run:

+```

+<build dir>/dump/dump.py mytrace.proto

+```

+

+## Example: Trace Build Process

+

+To show the capabilities of the UProcTrace, a process that calls several child

+processes is required. In this example, the build of UProcTrace is used for

+this purpose.

+

+Change to the build directory.

+

+Start a new shell to be traced:

+```

+bin/upt-trace mytrace.proto bash

+```

+

+Configure another build directory for this tracing example and run the build:

+

+```

+mkdir example_trace_build

+cd example_trace_build

+cmake -G Ninja -D CMAKE_BUILD_TYPE=Release ../..

+ninja

+```

+

+Stop tracing by ending the shell:

+

+```

+exit

+```

+

+Show traced information:

+```

+dump/dump.py mytrace.proto

+```

+

@@ -1 +1,2 @@

 add_subdirectory(first)

+add_subdirectory(trace_build)

@@ -2,18 +2,5 @@ add_test(

   NAME

   first

   COMMAND

-  bash -c

-  "

-    set -eux -o pipefail

-    > out.proto

-    (

-      export UPTPL_OUTPUT=out.proto

-      export LD_PRELOAD=${CMAKE_BINARY_DIR}/libuptpl/libuptpl.so

-      /bin/true a b 'c d'

-      /usr/bin/printf '' e f 'g h'

-    )

-    ls -l out.proto

-    ${CMAKE_BINARY_DIR}/dump/dump.py out.proto | tee out.dump

-    grep '^ *event *{ *$' out.dump | wc -l | grep '^4$'

-  "

+  ${CMAKE_CURRENT_SOURCE_DIR}/first.bash ${CMAKE_BINARY_DIR}

 )

@@ -0,0 +1,22 @@

+#! /bin/bash

+

+set -eux -o pipefail

+

+if (( $# < 1 ))

+then

+  echo "usage: $0 <UPT_HOME>" >&2

+  exit 2

+fi

+UPT_HOME="$1"

+

+SCRIPT_DIR="$(dirname "$0")"

+

+rm -rf out.proto

+

+"$UPT_HOME/bin/upt-trace" out.proto "$SCRIPT_DIR/traceme.bash"

+

+ls -l out.proto

+

+"$UPT_HOME/dump/dump.py" out.proto | tee out.dump

+grep '^ *event *{ *$' out.dump | wc -l | tee out.event_cnt

+grep '^6$' out.event_cnt

@@ -0,0 +1,3 @@

+#! /bin/bash

+/bin/true a b 'c d'

+/usr/bin/printf '' e f 'g h'

@@ -0,0 +1,7 @@

+add_test(

+  NAME

+  trace_build

+  COMMAND

+  ${CMAKE_CURRENT_SOURCE_DIR}/trace_build.bash ${CMAKE_SOURCE_DIR}

+                                               ${CMAKE_BINARY_DIR}

+)

@@ -0,0 +1,16 @@

+#! /bin/bash

+

+set -eux -o pipefail

+

+if (( $# < 1 ))

+then

+  echo "usage: $0 <SOURCE_DIR>" >&2

+  exit 2

+fi

+SOURCE_DIR="$(readlink -f "$1")"

+

+

+mkdir build

+cd build

+cmake -G Ninja -D CMAKE_BUILD_TYPE=Release "$SOURCE_DIR"

+ninja

@@ -0,0 +1,24 @@

+#! /bin/bash

+

+set -eux -o pipefail

+

+if (( $# < 2 ))

+then

+  echo "usage: $0 <SOURCE_DIR> <UPT_HOME>" >&2

+  exit 2

+fi

+SOURCE_DIR="$(readlink -f "$1")"

+UPT_HOME="$(readlink -f "$2")"

+

+SCRIPT_DIR="$(dirname "$0")"

+

+rm -rf out.proto build

+

+"$UPT_HOME/bin/upt-trace" out.proto "$SCRIPT_DIR/run_build.bash" "$SOURCE_DIR"

+

+ls -l out.proto

+

+"$UPT_HOME/dump/dump.py" out.proto | tee out.dump

+grep -A 1 '^ *cmdline {$' out.dump | grep '^ *s: "mkdir"$'

+grep '^ *s: "proc_begin.c"$' out.dump

+grep '^ *s: "libuptpl.so"$' out.dump

@@ -0,0 +1,16 @@

+add_custom_command(

+  OUTPUT

+  ${CMAKE_BINARY_DIR}/bin/upt-trace

+  DEPENDS

+  ${CMAKE_CURRENT_SOURCE_DIR}/upt-trace.bash

+  COMMAND

+  cp -a ${CMAKE_CURRENT_SOURCE_DIR}/upt-trace.bash

+        ${CMAKE_BINARY_DIR}/bin/upt-trace

+)

+

+add_custom_target(

+  upt-trace

+  ALL

+  DEPENDS

+  ${CMAKE_BINARY_DIR}/bin/upt-trace

+)

@@ -0,0 +1,17 @@

+#! /bin/bash

+

+if (( $# < 2 ))

+then

+  echo "usage: $0 <upt-trace-file.proto> <command> [<arg> [...]]" >&2

+  exit 2

+fi

+TRACE_FILE="$1"

+shift

+

+UPT_HOME="$(readlink -f "$(dirname "$(dirname "$0")")")"

+

+touch "$TRACE_FILE"

+export UPTPL_OUTPUT="$(readlink -f "$TRACE_FILE")"

+export LD_PRELOAD="$UPT_HOME/libuptpl/libuptpl.so"

+

+exec "$@"