Merge pull request #36 from cactusdynamics/cactus-tracing-4

Real-time tracing built directly into the framework with Perfetto-compatible data format

.github/workflows/main.yml

@@ -14,7 +14,7 @@ jobs:
  run: docker/scripts/00-format.sh
 
  - name: Setup dependencies
- run: sudo apt-get update && sudo apt-get install -y libspdlog-dev liblttng-ust-dev libboost-dev doxygen graphviz
+ run: sudo apt-get update && sudo apt-get install -y libspdlog-dev liblttng-ust-dev libboost-dev doxygen graphviz protobuf-compiler
 
  - name: Build library
  run: docker/scripts/01-build.sh

.gitignore

@@ -1,2 +1,4 @@
 build/
 .cache/
+
+.vscode/settings.json

.vscode/c_cpp_properties.json

@@ -5,7 +5,8 @@
  "includePath": [
  "${workspaceFolder}/include",
  "${workspaceFolder}/build/debug/_deps/**",
- "${workspaceFolder}/build/debug/_deps/readerwriterqueue-src"
+ "${workspaceFolder}/build/debug/_deps/readerwriterqueue-src",
+ "${workspaceFolder}/build/debug/protos"
  ],
  "defines": [],
  "compilerPath": "/usr/bin/gcc",
@@ -19,7 +20,8 @@
  "includePath": [
  "${workspaceFolder}/include",
  "${workspaceFolder}/build/release/_deps/**",
- "${workspaceFolder}/build/debug/_deps/readerwriterqueue-src"
+ "${workspaceFolder}/build/release/_deps/readerwriterqueue-src",
+ "${workspaceFolder}/build/release/protos"
  ],
  "defines": [],
  "compilerPath": "/usr/bin/gcc",

CMakeLists.txt

@@ -5,6 +5,7 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
 option(ENABLE_CLANG_TIDY "Run clang-tidy" OFF)
 option(ENABLE_EXAMPLES "Build example programs" ON)
+option(ENABLE_TRACING "Enable runtime tracing support" ON)
 option(BUILD_DOCS "Build documentations" OFF)
 
 # https://stackoverflow.com/questions/5395309/how-do-i-force-cmake-to-include-pthread-option-during-compilation
@@ -14,6 +15,10 @@ find_package(Threads REQUIRED)
 
 Include(FetchContent)
 
+#########################
+# External dependencies #
+#########################
+
 FetchContent_Declare(
  quill
  GIT_REPOSITORY https://github.com/odygrd/quill.git
@@ -41,37 +46,9 @@ FetchContent_MakeAvailable(readerwriterqueue)
 get_target_property(READERWRITERQUEUE_INC readerwriterqueue INTERFACE_INCLUDE_DIRECTORIES)
 set_target_properties(readerwriterqueue PROPERTIES INTERFACE_SYSTEM_INCLUDE_DIRECTORIES "${READERWRITERQUEUE_INC}")
 
-add_library(cactus_rt
- STATIC
- src/cactus_rt/app.cc
- src/cactus_rt/thread.cc
- src/cactus_rt/cyclic_thread.cc
- src/cactus_rt/signal_handler.cc
-)
-
-target_include_directories(cactus_rt
- PUBLIC
- ${CMAKE_CURRENT_SOURCE_DIR}/include
-)
-
-target_link_libraries(cactus_rt
- PUBLIC
- quill::quill
- readerwriterqueue
- PRIVATE
- Threads::Threads
-)
-
-# Use a bounded queue
-target_compile_definitions(cactus_rt PUBLIC QUILL_USE_BOUNDED_QUEUE)
-
-if(${CMAKE_PROJECT_NAME} STREQUAL ${PROJECT_NAME})
- if (ENABLE_CLANG_TIDY)
- find_program(CLANG_TIDY clang-tidy clang-tidy-17 clang-tidy-16 clang-tidy-15 clang-tidy-14)
- else()
- message(STATUS "Not running clang-tidy. Use ENABLE_CLANG_TIDY=ON to run clang-tidy.")
- endif()
-endif()
+##########################################################
+# Helper function to setup all cactus-rt related targets #
+##########################################################
 
 function(setup_cactus_rt_target_options target_name)
  # https://github.com/cpp-best-practices/cppbestpractices/blob/b1629eb/02-Use_the_Tools_Available.md#gcc--clang
@@ -117,6 +94,61 @@ function(setup_cactus_rt_target_options target_name)
  endif()
 endfunction()
 
+#####################
+# Cactus RT library #
+#####################
+
+if (ENABLE_TRACING)
+ add_subdirectory(protos)
+endif()
+
+add_library(cactus_rt
+ STATIC
+ src/cactus_rt/app.cc
+ src/cactus_rt/thread.cc
+ src/cactus_rt/cyclic_thread.cc
+ src/cactus_rt/signal_handler.cc
+)
+
+target_include_directories(cactus_rt
+ PUBLIC
+ ${CMAKE_CURRENT_SOURCE_DIR}/include
+)
+
+target_link_libraries(cactus_rt
+ PUBLIC
+ quill::quill
+ readerwriterqueue
+ PRIVATE
+ Threads::Threads
+)
+
+# Use a bounded queue
+target_compile_definitions(cactus_rt PUBLIC QUILL_USE_BOUNDED_QUEUE)
+
+if (ENABLE_TRACING)
+ target_sources(cactus_rt
+ PRIVATE
+ src/cactus_rt/tracing/tracing_enabled.cc
+ src/cactus_rt/tracing/sink.cc
+ src/cactus_rt/tracing/thread_tracer.cc
+ src/cactus_rt/tracing/trace_aggregator.cc
+ )
+
+ target_link_libraries(cactus_rt
+ PUBLIC
+ cactus_tracing_embedded_perfetto_protos
+ )
+endif()
+
+if(${CMAKE_PROJECT_NAME} STREQUAL ${PROJECT_NAME})
+ if (ENABLE_CLANG_TIDY)
+ find_program(CLANG_TIDY clang-tidy clang-tidy-17 clang-tidy-16 clang-tidy-15 clang-tidy-14)
+ else()
+ message(STATUS "Not running clang-tidy. Use ENABLE_CLANG_TIDY=ON to run clang-tidy.")
+ endif()
+endif()
+
 setup_cactus_rt_target_options(cactus_rt)
 
 # Build tests, examples, docs, only if this project is not embedded in another
@@ -137,6 +169,11 @@ if(${CMAKE_PROJECT_NAME} STREQUAL ${PROJECT_NAME})
  add_subdirectory(examples/signal_handling_example)
  add_subdirectory(examples/simple_deadline_example)
  add_subdirectory(examples/simple_example)
+
+ if (ENABLE_TRACING)
+ add_subdirectory(examples/tracing_protos_example)
+ add_subdirectory(examples/tracing_example)
+ endif()
  endif()
 
  if (BUILD_DOCS)

Makefile

@@ -1,10 +1,11 @@
 .PHONY: release debug clean clean-all
 
 ENABLE_CLANG_TIDY ?= OFF
+ENABLE_TRACING ?= ON
 ENABLE_EXAMPLES ?= ON
 BUILD_DOCS ?= OFF
 BUILD_TESTING ?= OFF
-CMAKE_FLAGS := -DENABLE_CLANG_TIDY=$(ENABLE_CLANG_TIDY) -DENABLE_EXAMPLES=$(ENABLE_EXAMPLES) -DBUILD_DOCS=$(BUILD_DOCS) -DBUILD_TESTING=$(BUILD_TESTING)
+CMAKE_FLAGS := -DENABLE_CLANG_TIDY=$(ENABLE_CLANG_TIDY) -DENABLE_EXAMPLES=$(ENABLE_EXAMPLES) -DBUILD_DOCS=$(BUILD_DOCS) -DBUILD_TESTING=$(BUILD_TESTING) -DENABLE_TRACING=$(ENABLE_TRACING)
 
 debug:
  cmake -Bbuild/$@ -DCMAKE_BUILD_TYPE=Debug $(CMAKE_FLAGS)

README.md

@@ -44,6 +44,7 @@ See each example's README for more details on what they do.
 * [`simple_deadline_example`](examples/simple_deadline_example/): Same as
  `simple_example`, except it uses `SCHED_DEADLINE` as opposed to `SCHED_FIFO`.
  This is for a more advanced use case.
+* [`tracing_example`](examples/tracing_example/): Shows how to dynamically start and stop tracing, as well as trace custom application functions.
 
 
 Installation instructions
@@ -60,11 +61,12 @@ Installation instructions
 * CMake
 * [Quill](https://github.com/odygrd/quill): this is included as a part of the CMake-based build process.
 * [`moodycamel::ReaderWriterQueue`](https://github.com/cameron314/readerwriterqueue): this is included as a part of the CMake-based build process.
+* Protobuf: for runtime tracing
 
 For Debian/Ubuntu:
 
 ```bash
-$ sudo apt install build-essential cmake
+$ sudo apt install build-essential cmake protobuf-compiler
 ```
 
 For building documentations, we need: doxygen.
@@ -143,3 +145,5 @@ LICENSE
 Open source projects and some commercial projects can use [MPL 2.0](https://www.mozilla.org/MPL/2.0/).
 
 If you need commercial, closed-sourced modifications, please obtain a license from [Cactus Dynamics](https://cactusdynamics.com).
+
+This library embeds work from [Perfetto](https://perfetto.dev), which is licensed under Apache License, version 2.

docker/Dockerfile

@@ -15,6 +15,7 @@ RUN set -xe; \
  lttng-tools \
  doxygen \
  graphviz \
+ protobuf-compiler \
  ; \
  mkdir /cactus-rt
 

docs/lockfree-queues.md

@@ -54,7 +54,3 @@ The best option from the above appears to be the the [`readerwriterqueue`][reade
 [^1]: More information about FUTEX_WAKE is found in this blog post's comments: https://timur.audio/using-locks-in-real-time-audio-processing-safely
 
 ### Data-passing architecture
-
-### Trace data format
-
-### Trace viewing