corecel/sys/TracingSession.hh

0001 //----------------------------------*-C++-*----------------------------------//
0002 // Copyright 2024 UT-Battelle, LLC, and other Celeritas developers.
0003 // See the top-level COPYRIGHT file for details.
0004 // SPDX-License-Identifier: (Apache-2.0 OR MIT)
0005 //---------------------------------------------------------------------------//
0006 //! \file corecel/sys/TracingSession.hh
0007 //! \brief RAII class for managing a perfetto session and its resources.
0008 //---------------------------------------------------------------------------//
0009 #pragma once
0010
0011 #include <memory>
0012 #include <string_view>
0013
0014 #include "corecel/Config.hh"
0015
0016 #include "corecel/Macros.hh"
0017
0018 //---------------------------------------------------------------------------//
0019 // Forward declarations
0020 //---------------------------------------------------------------------------//
0021
0022 namespace perfetto
0023 {
0024 //---------------------------------------------------------------------------//
0025 #if CELERITAS_USE_PERFETTO
0026 class TracingSession;
0027 #else
0028 //! Dummy as celeritas::TracingSession::~TracingSession needs a definition
0029 class TracingSession
0030 {
0031 };
0032 #endif
0033
0034 //---------------------------------------------------------------------------//
0035 }  // namespace perfetto
0036
0037 namespace celeritas
0038 {
0039 //---------------------------------------------------------------------------//
0040 //! Supported tracing mode
0041 enum class TracingMode : uint32_t
0042 {
0043     InProcess,  //!< Record in-process, writting to a file
0044     System  //!< Record in a system daemon
0045 };
0046
0047 //---------------------------------------------------------------------------//
0048 /*!
0049  * RAII wrapper for a tracing session.
0050  *
0051  * Constructors will only configure and initialize the session. It needs to
0052  * be started explicitly by calling \c TracingSession::start
0053  * Only a single tracing mode is supported. If you are only interested in
0054  * application-level events (\c ScopedProfiling and \c trace_counter),
0055  * then the in-process mode is sufficient and is enabled by providing the
0056  * trace data filename to the constructor. When using in-process tracing,
0057  * the buffer size can be configured by setting \c
0058  * CELER_PERFETTO_BUFFER_SIZE_MB.
0059  *
0060  * If no filename is provided, start a system tracing session which records
0061  * both application-level events and kernel events. Root privilege and
0062  * Linux ftrace https://kernel.org/doc/Documentation/trace/ftrace.txt are
0063  * required. To start the system daemons using the perfetto backend,
0064  * see https://perfetto.dev/docs/quickstart/linux-tracing#capturing-a-trace
0065  *
0066  * TODO: Support multiple tracing mode.
0067  */
0068 class TracingSession
0069 {
0070   public:
0071     // Configure a system session recording to a daemon
0072     TracingSession() noexcept;
0073
0074     // Configure an in-process session recording to filename
0075     explicit TracingSession(std::string_view filename) noexcept;
0076
0077     // Terminate the session and close open files
0078     ~TracingSession();
0079
0080     // Start the profiling session
0081     void start() noexcept;
0082
0083     //! Prevent copying but allow moving, following \c std::unique_ptr
0084     //! semantics
0085     TracingSession(TracingSession const&) = delete;
0086     TracingSession& operator=(TracingSession const&) = delete;
0087     TracingSession(TracingSession&&) noexcept;
0088     TracingSession& operator=(TracingSession&&) noexcept;
0089
0090   private:
0091     bool started_{false};
0092     std::unique_ptr<perfetto::TracingSession> session_;
0093     int fd_{-1};
0094 };
0095
0096 //---------------------------------------------------------------------------//
0097 // INLINE DEFINITIONS
0098 //---------------------------------------------------------------------------//
0099
0100 #if !CELERITAS_USE_PERFETTO
0101
0102 inline TracingSession::TracingSession() noexcept = default;
0103
0104 inline TracingSession::TracingSession(std::string_view) noexcept {}
0105
0106 inline TracingSession::~TracingSession() = default;
0107
0108 inline void TracingSession::start() noexcept
0109 {
0110     CELER_DISCARD(started_);
0111     CELER_DISCARD(fd_);
0112 }
0113
0114 #endif
0115
0116 //---------------------------------------------------------------------------//
0117 }  // namespace celeritas