Tracing v1.0

cmake/submodule_dependencies.cmake

@@ -15,6 +15,7 @@ set(ecal_submodule_dependencies
   HDF5
   #libssh2
   nanobind
+  nlohmann_json
   Protobuf
   protozero
   qwt

conanfile.py

@@ -17,6 +17,7 @@ def build_requirements(self):
     def requirements(self):
         self.requires("hdf5/1.10.6")
         self.requires("protobuf/3.17.1")
+        self.requires("nlohmann_json/3.11.2")
         self.requires("libcurl/7.78.0")
         self.requires("qt/5.15.2")
         self.requires("spdlog/1.9.2")
@@ -51,6 +52,6 @@ def generate(self):
         else:
             tc.variables["Protobuf_PROTOC_EXECUTABLE"] = os.path.join(self.deps_cpp_info["protobuf"].rootpath, "bin", "protoc")
         tc.generate()
-        
-        
-       
+
+
+

ecal/core/CMakeLists.txt

@@ -43,6 +43,7 @@ find_package(asio             REQUIRED)
 find_package(Threads          REQUIRED)
 find_package(ecaludp          REQUIRED)
 find_package(protozero        REQUIRED)
+find_package(nlohmann_json    REQUIRED)
 
 if (ECAL_CORE_CONFIGURATION)
   find_package(yaml-cpp       REQUIRED)
@@ -459,6 +460,23 @@ if(ECAL_CORE_TIMEPLUGIN)
   )
 endif()
 
+######################################
+# tracing
+######################################
+set(ecal_tracing_src
+    src/tracing/tracing.h
+    src/tracing/span.cpp
+    src/tracing/span.h
+    src/tracing/trace_provider.cpp
+    src/tracing/trace_provider.h
+    src/tracing/trace_provider_default.cpp
+    src/tracing/trace_provider_default.h
+    src/tracing/trace_provider_noop.h
+    src/tracing/tracing_writer.h
+    src/tracing/tracing_writer_jsonl.cpp
+    src/tracing/tracing_writer_jsonl.h
+)
+
 ######################################
 # util
 ######################################
@@ -637,6 +655,7 @@ set(ecal_sources
     ${ecal_serialization_src}
     ${ecal_service_src}
     ${ecal_time_src}
+    ${ecal_tracing_src}
     ${ecal_util_src}
     ${ecal_cmn_src}
     ${ecal_builder_src}
@@ -717,6 +736,8 @@ target_link_libraries(ecal_core_private
     $<$<BOOL:${ECAL_CORE_TRANSPORT_TCP}>:tcp_pubsub::tcp_pubsub>
     $<$<BOOL:${ECAL_CORE_TIMEPLUGIN}>:ecaltime>
     ecaludp::ecaludp
+    nlohmann_json::nlohmann_json
+    $<$<AND:$<BOOL:${UNIX}>,$<NOT:$<BOOL:${QNXNTO}>>>:dl>
     ${CMAKE_DL_LIBS}
     $<$<AND:$<BOOL:${UNIX}>,$<NOT:$<BOOL:${APPLE}>>,$<NOT:$<BOOL:${QNXNTO}>>>:rt>
     $<$<AND:$<BOOL:${UNIX}>,$<NOT:$<BOOL:${APPLE}>>,$<NOT:$<BOOL:${QNXNTO}>>>:atomic>

ecal/core/include/ecal/config/configuration.h

@@ -30,6 +30,7 @@
 #include <ecal/config/publisher.h>
 #include <ecal/config/subscriber.h>
 #include <ecal/config/time.h>
+#include <ecal/config/tracing.h>
 #include <ecal/types/custom_data_types.h>
 
 
@@ -58,6 +59,7 @@ namespace eCAL
     Time::Configuration           timesync;
     Application::Configuration    application;
     Logging::Configuration        logging;
+    Tracing::Configuration        tracing;
 
     eCommunicationMode            communication_mode { eCommunicationMode::local }; /*!< eCAL components communication mode:
                                                                                            local: local host only communication (default)

ecal/core/include/ecal/config/tracing.h

@@ -0,0 +1,38 @@
+/* ========================= eCAL LICENSE =================================
+ *
+ * Copyright (C) 2016 - 2025 Continental Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * ========================= eCAL LICENSE =================================
+*/
+
+/**
+ * @file   config/tracing.h
+ * @brief  eCAL tracing configuration
+**/
+
+#pragma once
+
+#include <string>
+
+namespace eCAL
+{
+  namespace Tracing
+  {
+    struct Configuration
+    {
+      bool enabled { false }; //!< Enable tracing (Default: false)
+    };
+  }
+}

ecal/core/include/ecal/util.h

@@ -64,6 +64,24 @@ namespace eCAL
     **/
     ECAL_API std::string GeteCALLogDir();
 
+    /**
+     * @brief Returns the path to the eCAL trace directory.
+     *
+     *        Searches in following order:
+     *        1. Environment variable ECAL_TRACE_DIR
+     *        2. Environment variable ECAL_DATA (also checking for traces subdirectory)
+    *        3. The path where ecal.yaml was loaded from (also checking for traces subdirectory)
+    *        4. The temporary directory (e.g. /tmp [unix], Appdata/local/Temp [win])
+    *        5. Fallback path /ecal_tmp
+     *
+    *        In case of 4/5, a unique temporary folder will be created.
+     *
+     * @returns The path to the eCAL trace directory.
+     *          The subdirectory traces might not exist yet.
+     *          Returns empty string if no root path could be found.
+    **/
+    ECAL_API std::string GeteCALTraceDir();
+
     /**
      * @brief Send shutdown event to specified local user process using it's unit name.
      *

ecal/core/src/config/configuration_to_yaml.cpp

@@ -671,6 +671,28 @@ namespace YAML
   }
 
 
+  /*
+     ______             _          
+    /_  __/______ _____(_)__  ___ _
+     / / / __/ _ `/ __/ / _ \/ _ `/
+    /_/ /_/  \_,_/\__/_/_//_/\_, / 
+                            /___/  
+  */
+
+  Node convert<eCAL::Tracing::Configuration>::encode(const eCAL::Tracing::Configuration& config_)
+  {
+    Node node;
+    node["enabled"] = config_.enabled;
+    return node;
+  }
+
+  bool convert<eCAL::Tracing::Configuration>::decode(const Node& node_, eCAL::Tracing::Configuration& config_)
+  {
+    AssignValue<bool>(config_.enabled, node_, "enabled");
+    return true;
+  }
+
+
   /*
        __  ___     _                      ____                    __  _         
       /  |/  /__ _(_)__    _______  ___  / _(_)__ ___ _________ _/ /_(_)__  ___ 
@@ -689,6 +711,7 @@ namespace YAML
     node["time"]               = config_.timesync;
     node["application"]        = config_.application;
     node["logging"]            = config_.logging;
+    node["tracing"]            = config_.tracing;
     node["communication_mode"] = config_.communication_mode == eCAL::eCommunicationMode::network ? "network" : "local";
 
     return node;
@@ -703,6 +726,7 @@ namespace YAML
     AssignValue<eCAL::Time::Configuration>(config_.timesync, node_, "time");
     AssignValue<eCAL::Application::Configuration>(config_.application, node_, "application");
     AssignValue<eCAL::Logging::Configuration>(config_.logging, node_, "logging");
+    AssignValue<eCAL::Tracing::Configuration>(config_.tracing, node_, "tracing");
 
     std::string communication_mode;
     AssignValue<std::string>(communication_mode, node_, "communication_mode");

ecal/core/src/config/configuration_to_yaml.h

@@ -343,6 +343,22 @@ namespace YAML
   };
 
 
+  /*
+     ______             _          
+    /_  __/______ _____(_)__  ___ _
+     / / / __/ _ `/ __/ / _ \/ _ `/
+    /_/ /_/  \_,_/\__/_/_//_/\_, / 
+                            /___/  
+  */
+  template<>
+  struct convert<eCAL::Tracing::Configuration>
+  {
+    static Node encode(const eCAL::Tracing::Configuration& config_);
+
+    static bool decode(const Node& node_, eCAL::Tracing::Configuration& config_);
+  };
+
+
   /*
        __  ___     _                      ____                    __  _         
       /  |/  /__ _(_)__    _______  ___  / _(_)__ ___ _________ _/ /_(_)__  ___ 

ecal/core/src/config/default_configuration.cpp

@@ -377,6 +377,11 @@ namespace eCAL
       ss << R"(      # UDP Port for sending logging data)"                                                                          << "\n";
       ss << R"(      port: )"                                         << config_.logging.receiver.udp_config.port                   << "\n";
       ss << R"()"                                                                                                                   << "\n";
+      ss << R"(# Tracing configuration)"                                                                                            << "\n";
+      ss << R"(tracing:)"                                                                                                           << "\n";
+      ss << R"(  # Enable tracing (Default: false))"                                                                                << "\n";
+      ss << R"(  enabled: )"                                          << config_.tracing.enabled                                    << "\n";
+      ss << R"()"                                                                                                                   << "\n";
 
       return ss;
     }

ecal/core/src/config/ecal_path_processing.cpp

@@ -178,6 +178,31 @@ namespace
 
   #endif
   }
+
+  std::string GeteCALOutputDirImpl(const eCAL::Util::IDirProvider& dir_provider_, const eCAL::Util::IDirManager& dir_manager_, const std::string& env_var_name_, const std::string& output_subdirectory_, const std::string& config_file_path_, const std::string& config_output_dir_)
+  {
+    const std::string config_file_dir = dir_manager_.getDirectoryPath(config_file_path_);
+    const std::string ecal_data_env_dir = dir_provider_.eCALEnvVar(ECAL_DATA_VAR);
+
+    const std::vector<std::string> output_paths = {
+      dir_provider_.eCALEnvVar(env_var_name_),
+      buildPath(ecal_data_env_dir, output_subdirectory_),
+      ecal_data_env_dir,
+      config_output_dir_,
+      buildPath(config_file_dir, output_subdirectory_),
+      config_file_dir
+    };
+
+    for (const auto& path : output_paths)
+    {
+      if (!path.empty() && dir_manager_.dirExists(path) && dir_manager_.canWriteToDirectory(path))
+      {
+        return path;
+      }
+    }
+
+    return dir_provider_.uniqueTmpDir(dir_manager_);
+  }
 }
 
 namespace eCAL
@@ -340,29 +365,15 @@ namespace eCAL
   {
     std::string GeteCALLogDirImpl(const Util::IDirProvider& dir_provider_ /* = Util::DirProvider() */, const Util::IDirManager& dir_manager_ /* = Util::DirManager() */, const eCAL::Configuration& config_ /* = eCAL::GetConfiguration() */)
     {
-      const std::string config_file_dir = dir_manager_.getDirectoryPath(eCAL::GetConfiguration().GetConfigurationFilePath());
-      const std::string ecal_data_env_dir = dir_provider_.eCALEnvVar(ECAL_DATA_VAR);
-
-      const std::vector<std::string> log_paths = {
-        dir_provider_.eCALEnvVar(ECAL_LOG_VAR),
-        buildPath(ecal_data_env_dir, ECAL_FOLDER_NAME_LOG),
-        ecal_data_env_dir,
-        config_.logging.provider.file_config.path,
-        buildPath(config_file_dir, ECAL_FOLDER_NAME_LOG),
-        config_file_dir
-      };
-
-      for (const auto& path : log_paths)
-      {
-        if (!path.empty() && dir_manager_.dirExists(path) && dir_manager_.canWriteToDirectory(path))
-        {
-          return path;
-        }
-      }
-
       // if no path is available, we create temp directories for logging
       // check now for a tmp directory and return
-      return dir_provider_.uniqueTmpDir(dir_manager_);
+      return GeteCALOutputDirImpl(dir_provider_, dir_manager_, ECAL_LOG_VAR, ECAL_FOLDER_NAME_LOG, config_.GetConfigurationFilePath(), config_.logging.provider.file_config.path);
+    }
+
+    std::string GeteCALTraceDirImpl(const Util::IDirProvider& dir_provider_ /* = Util::DirProvider() */, const Util::IDirManager& dir_manager_ /* = Util::DirManager() */, const eCAL::Configuration& config_ /* = eCAL::GetConfiguration() */)
+    {
+      // if no path is available, we create temp directories for tracing
+      return GeteCALOutputDirImpl(dir_provider_, dir_manager_, ECAL_TRACE_VAR, ECAL_FOLDER_NAME_TRACE, config_.GetConfigurationFilePath(), {});
     }
 
     std::string checkForValidConfigFilePath(const std::string& config_file_, const Util::DirProvider& dir_provider_ /* = Util::DirProvider() */, const Util::DirManager& dir_manager_ /* = Util::DirManager() */)

ecal/core/src/config/ecal_path_processing.h

@@ -221,6 +221,24 @@ namespace eCAL
      */
     std::string GeteCALLogDirImpl(const Util::IDirProvider& dir_provider_ = Util::DirProvider(), const Util::IDirManager& dir_manager_ = Util::DirManager(), const eCAL::Configuration& config_ = eCAL::GetConfiguration());
 
+    /**
+     * @brief Returns the path to the eCAL trace directory.
+     *
+     *        Searches in following order:
+     *        1. Environment variable ECAL_TRACE_DIR
+     *        2. Environment variable ECAL_DATA (also checking for traces subdirectory)
+     *        3. The path where ecal.yaml was loaded from (also checking for traces subdirectory)
+     *        4. The temporary directory (e.g. /tmp [unix], Appdata/local/Temp [win])
+     *        5. Fallback path /ecal_tmp
+     *
+     *        In case of 4/5, a unique temporary folder will be created.
+     *
+     * @returns The path to the eCAL trace directory.
+     *          The subdirectory traces might not exist yet.
+     *          Returns empty string if no root path could be found.
+     */
+    std::string GeteCALTraceDirImpl(const Util::IDirProvider& dir_provider_ = Util::DirProvider(), const Util::IDirManager& dir_manager_ = Util::DirManager(), const eCAL::Configuration& config_ = eCAL::GetConfiguration());
+
     /**
      * @brief Returns the path to the eCAL data directory. Searches in following order:
      *

ecal/core/src/ecal.cpp

@@ -118,6 +118,7 @@ namespace eCAL
       SetGlobalUnitName(unit_name_.c_str());
 
       if ((components_ & Init::Logging) != 0u) InitializeLogging(config_);
+      InitializeTracing(config_);
 
       auto globals_instance = CreateGlobalsInstance();
       if (!globals_instance) return false;
@@ -169,6 +170,7 @@ namespace eCAL
     ResetGlobalEcalConfiguration();
 
     ResetLogging();
+    ResetTracing();
 
     return finalized;
   }

ecal/core/src/ecal_def.h

@@ -35,6 +35,7 @@ constexpr const char* ECAL_FOLDER_NAME_WINDOWS      = "eCAL";
 constexpr const char* ECAL_FOLDER_NAME_LINUX        = "ecal";
 constexpr const char* ECAL_FOLDER_NAME_HOME_LINUX   = ".ecal";
 constexpr const char* ECAL_FOLDER_NAME_LOG          = "logs";
+constexpr const char* ECAL_FOLDER_NAME_TRACE        = "traces";
 constexpr const char* ECAL_FOLDER_NAME_TMP_WINDOWS  = "Temp";
 
 #ifdef ECAL_OS_WINDOWS
@@ -51,6 +52,7 @@ constexpr const char* ECAL_DEFAULT_CFG              = "ecal.yaml";
 /* environment variables */
 constexpr const char* ECAL_DATA_VAR                 = "ECAL_DATA";
 constexpr const char* ECAL_LOG_VAR                  = "ECAL_LOG_DIR";
+constexpr const char* ECAL_TRACE_VAR                = "ECAL_TRACE_DIR";
 constexpr const char* ECAL_LINUX_HOME_VAR           = "HOME";
 constexpr const char* ECAL_LINUX_TMP_VAR            = "TMPDIR";