corecel/sys/TracingSession.hh

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