Add action journal (#3409)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Bart Louwers <bart@emeel.net>

include/mbgl/map/map.hpp

@@ -13,6 +13,7 @@
 #include <mbgl/map/projection_mode.hpp>
 #include <mbgl/storage/resource_options.hpp>
 #include <mbgl/util/client_options.hpp>
+#include <mbgl/util/action_journal_options.hpp>
 
 #include <cstdint>
 #include <string>
@@ -31,13 +32,18 @@ class Image;
 class Style;
 } // namespace style
 
+namespace util {
+class ActionJournal;
+} // namespace util
+
 class Map : private util::noncopyable {
 public:
     explicit Map(RendererFrontend&,
                  MapObserver&,
                  const MapOptions&,
                  const ResourceOptions&,
-                 const ClientOptions& = ClientOptions());
+                 const ClientOptions& = ClientOptions(),
+                 const util::ActionJournalOptions& = util::ActionJournalOptions());
     ~Map();
 
     /// Register a callback that will get called (on the render thread) when all
@@ -152,12 +158,16 @@ public:
     void setFreeCameraOptions(const FreeCameraOptions& camera);
     FreeCameraOptions getFreeCameraOptions() const;
 
+    ClientOptions getClientOptions() const;
+
+    const std::unique_ptr<util::ActionJournal>& getActionJournal();
+
 protected:
     class Impl;
     const std::unique_ptr<Impl> impl;
 
     // For testing only.
-    Map(std::unique_ptr<Impl>);
+    Map(std::unique_ptr<Impl>, const util::ActionJournalOptions& = {});
 };
 
 } // namespace mbgl

include/mbgl/util/action_journal.hpp

@@ -0,0 +1,68 @@
+#pragma once
+
+#include <mbgl/map/map.hpp>
+#include <string>
+#include <vector>
+#include <memory>
+#include <filesystem>
+
+namespace mbgl {
+
+namespace util {
+
+class ActionJournalOptions;
+
+/**
+ * @brief Logs map events in a persistent rolling file format.
+ * Each event is stored as a serialized json object with the event data.
+ * Example
+ *  {
+ *      "name" : "onTileAction",
+ *      "time" : "2025-04-17T13:13:13.974Z",
+ *      "styleName" : "Streets",
+ *      "styleURL" : "maptiler://maps/streets",
+ *      "event" : {
+ *          "action" : "RequestedFromNetwork",
+ *          "tileX" : 0,
+ *          "tileY" : 0,
+ *          "tileZ" : 0,
+ *          "overscaledZ" : 0,
+ *          "sourceID" : "openmaptiles"
+ *      }
+ * }
+ */
+class ActionJournal {
+public:
+    ActionJournal(const Map& map, const ActionJournalOptions& options);
+    ~ActionJournal();
+
+    /**
+     * @brief Get the action journal umbrella directory containing all logs.
+     * @return log directory
+     */
+    std::string getLogDirectory() const;
+
+    /**
+     * @brief Get the action journal log files.
+     * @return list of log files
+     */
+    std::vector<std::string> getLogFiles() const;
+
+    /**
+     * @brief Get the action journal events from oldest to newest.
+     * Each element contains a serialized json object with the event data.
+     * @return List of serialized events
+     */
+    std::vector<std::string> getLog();
+
+    /**
+     * @brief Clear stored action journal events by removing logs files.
+     */
+    void clearLog();
+
+    class Impl;
+    const std::unique_ptr<Impl> impl;
+};
+
+} // namespace util
+} // namespace mbgl

include/mbgl/util/action_journal_options.hpp

@@ -0,0 +1,101 @@
+#pragma once
+
+#include <string>
+
+namespace mbgl {
+
+namespace util {
+
+/**
+ * @brief Holds values for Action Journal options.
+ */
+class ActionJournalOptions {
+public:
+    ActionJournalOptions() = default;
+    ~ActionJournalOptions() = default;
+
+    /**
+     * @brief Enable action journal event logging, defaults to false.
+     *
+     * @param value true to enable, false to disable.
+     * @return ActionJournalOptions for chaining options together.
+     */
+    ActionJournalOptions& enable(bool value = true) {
+        enable_ = value;
+        return *this;
+    }
+
+    /**
+     * @brief Gets the previously set (or default) value.
+     * @return Returns ActionJournal state
+     */
+    bool enabled() const { return enable_; }
+
+    /**
+     * @brief Set the log files location. An umbrela `action_journal` directory
+     * will be created at the given location containing all files.
+     *
+     * @param path Action Journal log path.
+     * @return ActionJournalOptions for chaining options together.
+     */
+    ActionJournalOptions& withPath(const std::string& path) {
+        path_ = path;
+        return *this;
+    }
+
+    /**
+     * @brief Gets the previously set (or default) log path.
+     * @return Returns ActionJournal log path
+     */
+    std::string path() const { return path_; }
+
+    /**
+     * @brief Set the file size for the log files. The action journal uses a
+     * rolling log with multiple files. Total log size is equal to
+     * `logFileSize * logFileCount`.
+     *
+     * @param size Action Journal log file size.
+     * @return ActionJournalOptions for chaining options together.
+     */
+    ActionJournalOptions& withLogFileSize(const uint32_t size) {
+        logFileSize_ = size;
+        return *this;
+    }
+
+    /**
+     * @brief Gets the previously set (or default) log file size.
+     * @return Returns ActionJournal log file size
+     */
+    uint32_t logFileSize() const { return logFileSize_; }
+
+    /**
+     * @brief Set the number of log files. The action journal uses a
+     * rolling log with multiple files. Total log size is equal to
+     * `logFileSize * logFileCount`.
+     *
+     * @param count Action Journal log file count.
+     * @return ActionJournalOptions for chaining options together.
+     */
+    ActionJournalOptions& withLogFileCount(const uint32_t count) {
+        logFileCount_ = count;
+        return *this;
+    }
+
+    /**
+     * @brief Gets the previously set (or default) number of log files.
+     * @return Returns ActionJournal log file count
+     */
+    uint32_t logFileCount() const { return logFileCount_; }
+
+protected:
+    bool enable_ = false;
+    // path of the log
+    std::string path_{"/tmp/"};
+    // log file size
+    uint32_t logFileSize_ = 1024 * 1024;
+    // number of log files (each of `logFileSize` size)
+    uint32_t logFileCount_ = 5;
+};
+
+} // namespace util
+} // namespace mbgl

include/mbgl/util/chrono.hpp

@@ -32,6 +32,9 @@ std::string rfc1123(Timestamp);
 // YYYY-mm-dd HH:MM:SS e.g. "2015-11-26 16:11:23"
 std::string iso8601(Timestamp);
 
+// YYYY-mm-ddTHH:MM:SS.MS e.g. "2015-11-26T16:11:23.324Z"
+std::string iso8601(std::chrono::time_point<std::chrono::system_clock, Milliseconds>);
+
 Timestamp parseTimestamp(const char *);
 
 Timestamp parseTimestamp(int32_t timestamp);