Support external (i.e. user-defined) trace annotations

.github/workflows/ubuntu-focal.yml

@@ -573,4 +573,3 @@ jobs:
           -DOMNITRACE_MAX_THREADS=32
           -DOMNITRACE_DISABLE_EXAMPLES="transpose;rccl"
           -DOMNITRACE_BUILD_NUMBER=${{ github.run_attempt }}
-          -DMPI_HEADERS_ALLOW_MPICH=ON

cmake/Packages.cmake

@@ -49,8 +49,10 @@ set(OMNITRACE_EXTENSION_LIBRARIES
     omnitrace::omnitrace-perfetto)
 
 target_include_directories(
-    omnitrace-headers INTERFACE ${PROJECT_SOURCE_DIR}/source/lib/omnitrace
-                                ${PROJECT_BINARY_DIR}/source/lib/omnitrace)
+    omnitrace-headers
+    INTERFACE ${PROJECT_BINARY_DIR}/source/lib ${PROJECT_BINARY_DIR}/source/lib/omnitrace
+              ${PROJECT_SOURCE_DIR}/source/lib ${PROJECT_SOURCE_DIR}/source/lib/omnitrace
+              ${PROJECT_SOURCE_DIR}/source/lib/omnitrace-user)
 
 # include threading because of rooflines
 target_link_libraries(omnitrace-headers INTERFACE omnitrace::omnitrace-threading)
@@ -372,7 +374,7 @@ else()
             OMNITRACE_DYNINST_API_RT dyninstAPI_RT
             HINTS ${Dyninst_ROOT_DIR} ${Dyninst_DIR}
             PATHS ${Dyninst_ROOT_DIR} ${Dyninst_DIR}
-            PATH_SUFFIXES lib)
+            PATH_SUFFIXES lib NO_CACHE)
 
         if(OMNITRACE_DYNINST_API_RT)
             omnitrace_target_compile_definitions(

examples/python/builtin.py

@@ -18,7 +18,7 @@ def inefficient(n):
         a += i
         for j in range(n):
             a += j
-    _len = a * n * n * n
+    _len = a * n * n
     _arr = [random.random() for _ in range(_len)]
     _sum = sum(_arr)
     print(f"[{_prefix}] ... sum of {_len} random elements: {_sum}")

examples/python/external.py

@@ -18,7 +18,7 @@ def inefficient(n):
         a += i
         for j in range(n):
             a += j
-    _len = a * n * n * n
+    _len = a * n * n
     _arr = [random.random() for _ in range(_len)]
     _sum = sum(_arr)
     print(f"[{_prefix}] ... sum of {_len} random elements: {_sum}")

examples/python/noprofile.py

@@ -20,7 +20,7 @@ def inefficient(n):
         a += i
         for j in range(n):
             a += j
-    _len = a * n * n * n
+    _len = a * n * n
     _arr = [random.random() for _ in range(_len)]
     _sum = sum(_arr)
     print(f"[{_prefix}] ... sum of {_len} random elements: {_sum}")

examples/python/source.py

@@ -23,7 +23,7 @@ def inefficient(n):
             a += i
             for j in range(n):
                 a += j
-        _len = a * n * n * n
+        _len = a * n * n
         _ret = np.random.rand(_len).sum()
         print(f"[{_prefix}] ... sum of {_len} random elements: {_ret}")
         return _ret
@@ -41,7 +41,7 @@ def inefficient(n):
             a += i
             for j in range(n):
                 a += j
-        _len = a * n * n * n
+        _len = a * n * n
         _arr = [random.random() for _ in range(_len)]
         _ret = _sum(_arr)
         print(f"[{_prefix}] ... sum of {_len} random elements: {_ret}")

examples/user-api/user-api.cpp

@@ -1,10 +1,14 @@
 
+#include "omnitrace/categories.h"
+#include "omnitrace/types.h"
 #include <omnitrace/user.h>
 
 #include <atomic>
 #include <cassert>
+#include <cerrno>
 #include <cstdio>
 #include <cstdlib>
+#include <cstring>
 #include <sstream>
 #include <thread>
 #include <vector>
@@ -22,19 +26,16 @@ custom_push_region(const char* name);
 
 namespace
 {
-int (*omnitrace_push_region_f)(const char*) = nullptr;
-}
+omnitrace_user_callbacks_t custom_callbacks   = OMNITRACE_USER_CALLBACKS_INIT;
+omnitrace_user_callbacks_t original_callbacks = OMNITRACE_USER_CALLBACKS_INIT;
+}  // namespace
 
 int
 main(int argc, char** argv)
 {
-    // get the internal callback to start a user-defined region
-    omnitrace_user_get_callbacks(OMNITRACE_USER_REGION, (void**) &omnitrace_push_region_f,
-                                 nullptr);
-    // assign the custom callback to start a user-defined region
-    if(omnitrace_push_region_f)
-        omnitrace_user_configure(OMNITRACE_USER_REGION, (void*) &custom_push_region,
-                                 nullptr);
+    custom_callbacks.push_region = &custom_push_region;
+    omnitrace_user_configure(OMNITRACE_USER_UNION_CONFIG, custom_callbacks,
+                             &original_callbacks);
 
     omnitrace_user_push_region(argv[0]);
     omnitrace_user_push_region("initialization");
@@ -100,6 +101,26 @@ run(size_t nitr, long n)
 int
 custom_push_region(const char* name)
 {
+    if(!original_callbacks.push_region || !original_callbacks.push_annotated_region)
+        return OMNITRACE_USER_ERROR_NO_BINDING;
+
     printf("Pushing custom region :: %s\n", name);
-    return (*omnitrace_push_region_f)(name);
+
+    if(original_callbacks.push_annotated_region)
+    {
+        int32_t _err = errno;
+        char*   _msg = nullptr;
+        char    _buff[1024];
+        if(_err != 0) _msg = strerror_r(_err, _buff, sizeof(_buff));
+
+        omnitrace_annotation_t _annotations[] = {
+            { "errno", OMNITRACE_INT32, &_err }, { "strerror", OMNITRACE_STRING, _msg }
+        };
+
+        errno = 0;  // reset errno
+        return (*original_callbacks.push_annotated_region)(
+            name, _annotations, sizeof(_annotations) / sizeof(omnitrace_annotation_t));
+    }
+
+    return (*original_callbacks.push_region)(name);
 }

source/lib/common/defines.h.in

@@ -74,6 +74,7 @@
 #define OMNITRACE_INLINE            OMNITRACE_ATTRIBUTE(always_inline) inline
 #define OMNITRACE_NOINLINE          OMNITRACE_ATTRIBUTE(noinline)
 #define OMNITRACE_HOT               OMNITRACE_ATTRIBUTE(hot)
+#define OMNITRACE_COLD              OMNITRACE_ATTRIBUTE(cold)
 #define OMNITRACE_CONST             OMNITRACE_ATTRIBUTE(const)
 #define OMNITRACE_PURE              OMNITRACE_ATTRIBUTE(pure)
 #define OMNITRACE_WEAK              OMNITRACE_ATTRIBUTE(weak)

source/lib/omnitrace-dl/dl.cpp

@@ -39,6 +39,8 @@
 #include "common/join.hpp"
 #include "common/setup.hpp"
 #include "dl.hpp"
+#include "omnitrace/categories.h"
+#include "omnitrace/types.h"
 
 #include <cassert>
 #include <gnu/libc-version.h>
@@ -256,6 +258,10 @@ struct OMNITRACE_HIDDEN_API indirect
         OMNITRACE_DLSYM(omnitrace_pop_trace_f, m_omnihandle, "omnitrace_pop_trace");
         OMNITRACE_DLSYM(omnitrace_push_region_f, m_omnihandle, "omnitrace_push_region");
         OMNITRACE_DLSYM(omnitrace_pop_region_f, m_omnihandle, "omnitrace_pop_region");
+        OMNITRACE_DLSYM(omnitrace_push_category_region_f, m_omnihandle,
+                        "omnitrace_push_category_region");
+        OMNITRACE_DLSYM(omnitrace_pop_category_region_f, m_omnihandle,
+                        "omnitrace_pop_category_region");
         OMNITRACE_DLSYM(omnitrace_register_source_f, m_omnihandle,
                         "omnitrace_register_source");
         OMNITRACE_DLSYM(omnitrace_register_coverage_f, m_omnihandle,
@@ -330,37 +336,43 @@ struct OMNITRACE_HIDDEN_API indirect
 
         if(omnitrace_user_configure_f)
         {
-            (*omnitrace_user_configure_f)(
-                OMNITRACE_USER_START_STOP,
-                reinterpret_cast<void*>(&omnitrace_user_start_trace_dl),
-                reinterpret_cast<void*>(&omnitrace_user_stop_trace_dl));
-            (*omnitrace_user_configure_f)(
-                OMNITRACE_USER_START_STOP_THREAD,
-                reinterpret_cast<void*>(&omnitrace_user_start_thread_trace_dl),
-                reinterpret_cast<void*>(&omnitrace_user_stop_thread_trace_dl));
-            (*omnitrace_user_configure_f)(
-                OMNITRACE_USER_REGION,
-                reinterpret_cast<void*>(&omnitrace_user_push_region_dl),
-                reinterpret_cast<void*>(&omnitrace_user_pop_region_dl));
+            omnitrace_user_callbacks_t _cb = {};
+            _cb.start_trace                = &omnitrace_user_start_trace_dl;
+            _cb.stop_trace                 = &omnitrace_user_stop_trace_dl;
+            _cb.start_thread_trace         = &omnitrace_user_start_thread_trace_dl;
+            _cb.stop_thread_trace          = &omnitrace_user_stop_thread_trace_dl;
+            _cb.push_region                = &omnitrace_user_push_region_dl;
+            _cb.pop_region                 = &omnitrace_user_pop_region_dl;
+            _cb.push_annotated_region      = &omnitrace_user_push_annotated_region_dl;
+            _cb.pop_annotated_region       = &omnitrace_user_pop_annotated_region_dl;
+            (*omnitrace_user_configure_f)(OMNITRACE_USER_REPLACE_CONFIG, _cb, nullptr);
         }
     }
 
 public:
-    // omnitrace functions
-    void (*omnitrace_init_library_f)(void)                                  = nullptr;
-    void (*omnitrace_init_tooling_f)(void)                                  = nullptr;
-    void (*omnitrace_init_f)(const char*, bool, const char*)                = nullptr;
-    void (*omnitrace_finalize_f)(void)                                      = nullptr;
-    void (*omnitrace_set_env_f)(const char*, const char*)                   = nullptr;
-    void (*omnitrace_set_mpi_f)(bool, bool)                                 = nullptr;
+    using user_cb_t = omnitrace_user_callbacks_t;
+
+    // libomnitrace functions
+    void (*omnitrace_init_library_f)(void)                                   = nullptr;
+    void (*omnitrace_init_tooling_f)(void)                                   = nullptr;
+    void (*omnitrace_init_f)(const char*, bool, const char*)                 = nullptr;
+    void (*omnitrace_finalize_f)(void)                                       = nullptr;
+    void (*omnitrace_set_env_f)(const char*, const char*)                    = nullptr;
+    void (*omnitrace_set_mpi_f)(bool, bool)                                  = nullptr;
     void (*omnitrace_register_source_f)(const char*, const char*, size_t, size_t,
-                                        const char*)                        = nullptr;
-    void (*omnitrace_register_coverage_f)(const char*, const char*, size_t) = nullptr;
-    void (*omnitrace_push_trace_f)(const char*)                             = nullptr;
-    void (*omnitrace_pop_trace_f)(const char*)                              = nullptr;
-    int (*omnitrace_push_region_f)(const char*)                             = nullptr;
-    int (*omnitrace_pop_region_f)(const char*)                              = nullptr;
-    int (*omnitrace_user_configure_f)(int, void*, void*)                    = nullptr;
+                                        const char*)                         = nullptr;
+    void (*omnitrace_register_coverage_f)(const char*, const char*, size_t)  = nullptr;
+    void (*omnitrace_push_trace_f)(const char*)                              = nullptr;
+    void (*omnitrace_pop_trace_f)(const char*)                               = nullptr;
+    int (*omnitrace_push_region_f)(const char*)                              = nullptr;
+    int (*omnitrace_pop_region_f)(const char*)                               = nullptr;
+    int (*omnitrace_push_category_region_f)(omnitrace_category_t, const char*,
+                                            omnitrace_annotation_t*, size_t) = nullptr;
+    int (*omnitrace_pop_category_region_f)(omnitrace_category_t, const char*,
+                                           omnitrace_annotation_t*, size_t)  = nullptr;
+
+    // libomnitrace-user functions
+    int (*omnitrace_user_configure_f)(int, user_cb_t, user_cb_t*) = nullptr;
 
     // KokkosP functions
     void (*kokkosp_print_help_f)(char*)                                       = nullptr;
@@ -626,30 +638,66 @@ extern "C"
         }
     }
 
-    void omnitrace_push_region(const char* name)
+    int omnitrace_push_region(const char* name)
     {
-        if(!dl::get_active()) return;
+        if(!dl::get_active()) return 0;
         if(dl::get_thread_enabled())
         {
-            OMNITRACE_DL_INVOKE(get_indirect().omnitrace_push_region_f, name);
+            return OMNITRACE_DL_INVOKE(get_indirect().omnitrace_push_region_f, name);
         }
         else
         {
             ++dl::get_thread_count();
         }
+        return 0;
     }
 
-    void omnitrace_pop_region(const char* name)
+    int omnitrace_pop_region(const char* name)
     {
-        if(!dl::get_active()) return;
+        if(!dl::get_active()) return 0;
         if(dl::get_thread_enabled())
         {
-            OMNITRACE_DL_INVOKE(get_indirect().omnitrace_pop_region_f, name);
+            return OMNITRACE_DL_INVOKE(get_indirect().omnitrace_pop_region_f, name);
         }
         else
         {
             if(dl::get_thread_count()-- == 0) omnitrace_user_start_thread_trace_dl();
         }
+        return 0;
+    }
+
+    int omnitrace_push_category_region(omnitrace_category_t _category, const char* name,
+                                       omnitrace_annotation_t* _annotations,
+                                       size_t                  _annotation_count)
+    {
+        if(!dl::get_active()) return 0;
+        if(dl::get_thread_enabled())
+        {
+            return OMNITRACE_DL_INVOKE(get_indirect().omnitrace_push_category_region_f,
+                                       _category, name, _annotations, _annotation_count);
+        }
+        else
+        {
+            ++dl::get_thread_count();
+        }
+        return 0;
+    }
+
+    int omnitrace_pop_category_region(omnitrace_category_t _category, const char* name,
+                                      omnitrace_annotation_t* _annotations,
+                                      size_t                  _annotation_count)
+    {
+        if(!dl::get_active()) return 0;
+        if(dl::get_thread_enabled())
+        {
+            return OMNITRACE_DL_INVOKE(get_indirect().omnitrace_pop_category_region_f,
+                                       _category, name, _annotations, _annotation_count);
+        }
+        else
+        {
+            ++dl::get_thread_count();
+        }
+        return 0;
     }
 
     void omnitrace_set_env(const char* a, const char* b)
@@ -724,6 +772,26 @@ extern "C"
         return OMNITRACE_DL_INVOKE(get_indirect().omnitrace_pop_region_f, name);
     }
 
+    int omnitrace_user_push_annotated_region_dl(const char*             name,
+                                                omnitrace_annotation_t* _annotations,
+                                                size_t                  _annotation_count)
+    {
+        if(!dl::get_active()) return 0;
+        return OMNITRACE_DL_INVOKE(get_indirect().omnitrace_push_category_region_f,
+                                   OMNITRACE_CATEGORY_USER, name, _annotations,
+                                   _annotation_count);
+    }
+
+    int omnitrace_user_pop_annotated_region_dl(const char*             name,
+                                               omnitrace_annotation_t* _annotations,
+                                               size_t                  _annotation_count)
+    {
+        if(!dl::get_active()) return 0;
+        return OMNITRACE_DL_INVOKE(get_indirect().omnitrace_pop_category_region_f,
+                                   OMNITRACE_CATEGORY_USER, name, _annotations,
+                                   _annotation_count);
+    }
+
     //----------------------------------------------------------------------------------//
     //
     //      KokkosP

source/lib/omnitrace-dl/dl.hpp

@@ -21,7 +21,7 @@
 // SOFTWARE.
 
 #ifndef OMNITRACE_DL_HPP_
-#define OMNITRACE_DL_HPP_ 1
+#define OMNITRACE_DL_HPP_
 
 #if defined(OMNITRACE_DL_SOURCE) && (OMNITRACE_DL_SOURCE > 0)
 #    include "common/defines.h"
@@ -78,8 +78,15 @@ extern "C"
     void omnitrace_set_mpi(bool use, bool attached) OMNITRACE_PUBLIC_API;
     void omnitrace_push_trace(const char* name) OMNITRACE_PUBLIC_API;
     void omnitrace_pop_trace(const char* name) OMNITRACE_PUBLIC_API;
-    void omnitrace_push_region(const char*) OMNITRACE_PUBLIC_API;
-    void omnitrace_pop_region(const char*) OMNITRACE_PUBLIC_API;
+    int  omnitrace_push_region(const char*) OMNITRACE_PUBLIC_API;
+    int  omnitrace_pop_region(const char*) OMNITRACE_PUBLIC_API;
+    int  omnitrace_push_category_region(omnitrace_category_t, const char*,
+                                        omnitrace_annotation_t*,
+                                        size_t) OMNITRACE_PUBLIC_API;
+    int  omnitrace_pop_category_region(omnitrace_category_t, const char*,
+                                       omnitrace_annotation_t*,
+                                       size_t) OMNITRACE_PUBLIC_API;
+
     void omnitrace_register_source(const char* file, const char* func, size_t line,
                                    size_t      address,
                                    const char* source) OMNITRACE_PUBLIC_API;
@@ -99,6 +106,11 @@ extern "C"
     int omnitrace_user_push_region_dl(const char*) OMNITRACE_HIDDEN_API;
     int omnitrace_user_pop_region_dl(const char*) OMNITRACE_HIDDEN_API;
 
+    int omnitrace_user_push_annotated_region_dl(const char*, omnitrace_annotation_t*,
+                                                size_t) OMNITRACE_HIDDEN_API;
+    int omnitrace_user_pop_annotated_region_dl(const char*, omnitrace_annotation_t*,
+                                               size_t) OMNITRACE_HIDDEN_API;
+
     // KokkosP
     struct OMNITRACE_HIDDEN_API SpaceHandle
     {

source/lib/omnitrace-user/CMakeLists.txt

@@ -35,9 +35,11 @@ set_target_properties(
 
 omnitrace_strip_target(omnitrace-user-library)
 
-install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/omnitrace/user.h
-              ${CMAKE_CURRENT_SOURCE_DIR}/omnitrace/types.h
-        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/omnitrace)
+install(
+    FILES ${CMAKE_CURRENT_SOURCE_DIR}/omnitrace/user.h
+          ${CMAKE_CURRENT_SOURCE_DIR}/omnitrace/types.h
+          ${CMAKE_CURRENT_SOURCE_DIR}/omnitrace/categories.h
+    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/omnitrace)
 
 install(
     TARGETS omnitrace-user-library