add support for process-level tracing (#2)

Author: d99kris

CMakeLists.txt

@@ -16,7 +16,7 @@ install(FILES ${CMAKE_CURRENT_BINARY_DIR}/share/man/man1/cpuusage.1 DESTINATION
 
 # Catapult
 if (NOT IS_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/share/cpuusage/catapult)
-  execute_process(COMMAND ${CMAKE_COMMAND} -E tar -xzvf ${CMAKE_SOURCE_DIR}/catapult.tar.gz)
+  execute_process(COMMAND ${CMAKE_COMMAND} -E tar -xzvf ${CMAKE_SOURCE_DIR}/ext/catapult.tar.gz)
 endif ()
 install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/share/cpuusage/catapult DESTINATION share/cpuusage)
 
@@ -64,6 +64,11 @@ target_link_libraries(${PROJECT_NAME} dl)
 target_link_libraries(${PROJECT_NAME}static dl)
 install(TARGETS ${PROJECT_NAME} DESTINATION lib)
 
+# Cpuusageproc library build
+add_library(${PROJECT_NAME}proc SHARED src/cupmain.cpp)
+target_link_libraries(${PROJECT_NAME}proc dl)
+install(TARGETS ${PROJECT_NAME}proc DESTINATION lib)
+
 # Example - ex001 - regular program / non-instrumented
 add_executable(ex001 tests/ex.c)
 target_link_libraries(ex001 pthread)
@@ -77,6 +82,14 @@ target_link_libraries(ex002 pthread cpuusage)
 add_executable(ex003 tests/ex3.cpp src/cpuusage.h)
 target_link_libraries(ex003 pthread cpuusage)
 
+# Example - ex004 - simple program (sleep)
+add_executable(ex004 tests/ex4.cpp)
+target_link_libraries(ex004)
+
+# Example - ex005 - simple scripts
+configure_file(tests/ex5.sh ${CMAKE_CURRENT_BINARY_DIR}/ex005.sh COPYONLY)
+configure_file(tests/ex5b.sh ${CMAKE_CURRENT_BINARY_DIR}/ex005b.sh COPYONLY)
+
 # Tests
 enable_testing()
 
@@ -89,3 +102,11 @@ add_test(test002 "${PROJECT_BINARY_DIR}/test002")
 configure_file(tests/test003 ${CMAKE_CURRENT_BINARY_DIR}/test003 COPYONLY)
 add_test(test003 "${PROJECT_BINARY_DIR}/test003")
 
+configure_file(tests/test004 ${CMAKE_CURRENT_BINARY_DIR}/test004 COPYONLY)
+add_test(test004 "${PROJECT_BINARY_DIR}/test004")
+
+if(UNIX AND NOT APPLE)
+  configure_file(tests/test005 ${CMAKE_CURRENT_BINARY_DIR}/test005 COPYONLY)
+  add_test(test005 "${PROJECT_BINARY_DIR}/test005")
+endif()
+

DESIGN.md

@@ -58,6 +58,7 @@ General syntax:
     cpuusage -c [OPTIONS] PROG [ARGS..]
     cpuusage -f <FUNCTIONS> [OPTIONS] PROG [ARGS..]
     cpuusage -i <INCLUDES> [OPTIONS] PROG [ARGS..]
+    cpuusage -p [OPTIONS] PROG [ARGS..]
     cpuusage -r JSONFILE [OPTIONS]
     cpuusage --help|-h
     cpuusage --version|-v
@@ -77,6 +78,8 @@ Options:
     -i <INCLUDES>
            trace functions in specified POSIX headers
 
+    -p     trace child process durations
+
     --help, -h
            display this help and exit
 
@@ -101,6 +104,8 @@ Options:
 
     -v     verbose mode
 
+    -y     auto-open resulting html file
+
     PROG   program to run and profile
 
     [ARGS] optional arguments to the program
@@ -146,6 +151,18 @@ Resulting visualization:
 Resulting visualization:
 ![culog4 screenshot](/doc/culog4.png)
 
+**Tracing process durations:**
+
+    $ cpuusage -v -o cutrace5.html -p ./ex005.sh 
+    cpuusage: https://github.com/d99kris/cpuusage
+    cpuusage: initializing
+    cpuusage: starting program ./ex005.sh
+    cpuusage: processing output trace
+    cpuusage: completed processing 5 samples
+
+Resulting visualization:
+![culog5 screenshot](/doc/culog5.png)
+
 Alternatives
 ============
 There are many CPU profilers available for Linux and macOS. Most of them are
@@ -157,7 +174,8 @@ sample-based, and here is a list of some of them:
 
 Technical Details
 =================
-Refer to [DESIGN.md](DESIGN.md) for design and implementation details.
+Refer to [ext/README.md](/ext/README.md) for details on the external components
+used by cpuusage.
 
 License
 =======

README.md

@@ -0,0 +1,47 @@
+External Components
+===================
+This directory contains external components used by cpuusage.
+
+Catapult
+--------
+Catapult is the most important third-party component of cpuusage. Not the entire
+Catapult software is needed by cpuusage, so only a part of the original package
+is distributed with cpuusage. It is compressed and located in catapult.tar.gz
+
+### Trace File Format
+Cpuusage generates JSON files following the
+[Trace Event Format](/ext/catapult_trace_event_format.pdf) which subsequently
+is converted by Catapult into a HTML report.
+
+The Trace Event Format PDF was generated from the Google Document
+[Trace Event Format](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/edit)
+linked from [Catapult Tracing](https://chromium.googlesource.com/catapult/+/HEAD/tracing/README.md).
+
+### Updating Catapult
+In case Catapult needs to be updated (it happened when updating to Python 3.x
+support) the recommended method is:
+
+1.  Build cpuusage
+
+    ./genman.sh
+
+2.  Run tests
+
+    cd build && ctest --output-on-failure
+
+3.  Perform any necessary updates to the Catapult copy in
+    build/share/cpuusage/catapult to make tests pass.
+
+4.  When all tests are passing, create a new tar-ball and make sure to exclude
+    test_data, e.g. `rm -rf share/cpuusage/catapult/tracing/test_data`
+    The tar-ball can be created like this:
+
+    tar -czvf ~/c1.tar.gz share/cpuusage/catapult
+   
+    Then replace the original file:
+
+    cp ~/c1.tar.gz ../ext/catapult.tar.gz
+
+5.  Finally delete the previous build directory and try build and run tests
+    again.
+

doc/culog5.png

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+
+BUILD="0"
+INSTALL="0"
+TESTS="0"
+case "${1%/}" in
+  build)
+    BUILD="1"
+    ;;
+
+  install)
+    BUILD="1"
+    INSTALL="1"
+    ;;
+
+  tests)
+    BUILD="1"
+    TESTS="1"
+    ;;
+
+  *)
+    echo "usage: make.sh <build|install|tests>"
+    echo "  build     - build"
+    echo "  install   - perform build, tests and install"
+    echo "  tests     - perform build and run tests"
+    exit 1
+    ;;
+esac
+
+if [[ "${BUILD}" == "1" ]]; then
+  if [[ "$(which help2man)" != "" ]]; then
+    cd src && help2man -n "instrumentation CPU profiler" -N -o cpuusage.1 ./cpuusage && cd - > /dev/null
+    if [[ "${?}" == "0" ]]; then
+      if [[ "$(uname)" == "Darwin" ]]; then
+        SED="gsed -i"
+      else
+        SED="sed -i"
+      fi
+      ${SED} "s/\.\\\\\" DO NOT MODIFY THIS FILE\!  It was generated by help2man.*/\.\\\\\" DO NOT MODIFY THIS FILE\!  It was generated by help2man./g" src/cpuusage.1
+    else
+      echo "generate man-page failed, exiting."
+      exit 1
+    fi
+  else
+    echo "generate man-page skipped, help2man not present."
+  fi
+  
+  mkdir -p build && cd build && cmake .. && make -s
+  if [[ "${?}" != "0" ]]; then
+    echo "build failed, exiting."
+    exit 1
+  fi
+  cd - > /dev/null
+fi
+
+if [[ "${TESTS}" == "1" ]]; then
+  cd build && ctest --output-on-failure
+  if [[ "${?}" != "0" ]]; then
+    echo "tests failed, exiting."
+    exit 1
+  fi
+  cd - > /dev/null
+fi
+
+if [[ "${INSTALL}" == "1" ]]; then
+  INSTALLCMD=""
+  if [[ "$(uname)" == "Linux" ]]; then
+    INSTALLCMD="sudo"
+  fi
+  
+  cd build && ${INSTALLCMD} make -s install
+  if [[ "${?}" != "0" ]]; then
+    echo "install failed, exiting."
+    exit 1
+  fi
+  cd - > /dev/null
+fi
+
+exit 0