feat(logging): add registerable FatalHandler before abort (#725 review ⑤)

Address the extensibility comment: let an embedder (JNI, Python host, crash
reporter) run a hook on the fatal path before std::abort() to flush resources or
print a stack trace.

- Add FatalHandler = std::function<void(const std::source_location&,
  std::string_view)> plus thread-safe SetFatalHandler/GetFatalHandler (leaked,
  teardown-safe slot in logger.cc).
- Wire it into LogFatal: format the message once, emit-if-enabled + flush, run the
  handler (message passed even when the record is filtered out), then abort. A
  throwing handler cannot prevent the abort.
- Death tests: handler runs with the formatted message, receives the call-site
  location, and still fires when the record is suppressed.

Co-authored-by: Isaac

Author: kamcheungting-db

src/iceberg/CMakeLists.txt

@@ -193,10 +193,10 @@ add_iceberg_lib(iceberg
                 OUTPUTS
                 ICEBERG_LIBRARIES)
 
-# The logging macros in the public logger.h use __VA_OPT__, which MSVC's
-# traditional preprocessor rejects. Require the conforming preprocessor PUBLICly
-# so both these library targets (logger.cc includes logger.h) and downstream
-# consumers of the installed header get it on MSVC.
+# The logging macros in the installed public header log_macros.h use __VA_OPT__,
+# which MSVC's traditional preprocessor rejects. Require the conforming
+# preprocessor PUBLICly so downstream consumers that include log_macros.h get it
+# on MSVC (and any library TU that includes it does too).
 if(MSVC_TOOLCHAIN)
   foreach(_iceberg_lib iceberg_shared iceberg_static)
     if(TARGET ${_iceberg_lib})

src/iceberg/logging/log_macros.h

@@ -108,16 +108,35 @@ void LogToExplicitRuntime(Logger& logger, LogLevel level,
 }
 
 /// \brief Fatal path: acquire the effective (scoped-or-default) logger ONCE, emit
-/// if enabled, flush that same logger, then abort. Never returns.
+/// if enabled, flush that same logger, run any registered FatalHandler, then
+/// abort. Never returns.
+///
+/// The message is always formatted here (independent of ShouldLog) so the handler
+/// receives it even when the fatal record itself is filtered out. The handler runs
+/// after emit+flush and before abort; if it does not itself terminate the process,
+/// std::abort() still runs.
 template <typename MakeMessage>
 [[noreturn]] void LogFatal(const std::source_location& location,
                            MakeMessage&& make_message) noexcept {
+  std::string message;
+  try {
+    message = std::forward<MakeMessage>(make_message)();
+  } catch (...) {
+    message = "<fmt error>";
+  }
   auto logger = GetCurrentLogger();
   if (logger) {
-    EmitIfEnabled(*logger, LogLevel::kFatal, location,
-                  std::forward<MakeMessage>(make_message));
+    if (logger->ShouldLog(LogLevel::kFatal)) {
+      Emit(*logger, LogLevel::kFatal, location, std::string(message));
+    }
     logger->Flush();
   }
+  if (auto handler = GetFatalHandler()) {
+    try {
+      handler(location, message);
+    } catch (...) {  // a throwing handler must not prevent the abort
+    }
+  }
   std::abort();
 }
 

src/iceberg/logging/logger.cc

@@ -106,6 +106,35 @@ void SetDefaultLevel(LogLevel level) {
   slot.logger->SetLevel(level);
 }
 
+namespace {
+
+/// \brief Immortal (leaked, hence teardown-safe) home for the fatal handler and
+/// its mutex. Leaked like Slot() so GetFatalHandler() is valid even during static
+/// teardown / from the fatal path at any time.
+struct FatalHandlerSlot {
+  std::mutex mtx;
+  FatalHandler handler;
+};
+
+FatalHandlerSlot& FatalSlot() {
+  static auto* slot = new FatalHandlerSlot();
+  return *slot;
+}
+
+}  // namespace
+
+void SetFatalHandler(FatalHandler handler) {
+  FatalHandlerSlot& slot = FatalSlot();
+  std::lock_guard<std::mutex> lock(slot.mtx);
+  slot.handler = std::move(handler);
+}
+
+FatalHandler GetFatalHandler() {
+  FatalHandlerSlot& slot = FatalSlot();
+  std::lock_guard<std::mutex> lock(slot.mtx);
+  return slot.handler;  // copy under lock; safe to invoke without holding the lock
+}
+
 namespace internal {
 
 namespace {

src/iceberg/logging/logger.h

@@ -29,6 +29,7 @@
 #include <concepts>
 #include <cstdlib>
 #include <format>
+#include <functional>
 #include <memory>
 #include <source_location>
 #include <string>
@@ -211,6 +212,26 @@ ICEBERG_EXPORT void SetDefaultLogger(std::shared_ptr<Logger> logger);
 /// means (this, SetLevel on a held handle, or Initialize) takes effect immediately.
 ICEBERG_EXPORT void SetDefaultLevel(LogLevel level);
 
+/// \brief A hook invoked on the fatal-log path just before std::abort().
+///
+/// Receives the fatal record's source location and already-formatted message.
+/// Runs after the record has been emitted and the logger flushed, so an embedder
+/// (JNI, a Python host, a crash reporter) can print a stack trace, flush its own
+/// resources, or translate the abort. It must not return normally on the
+/// expectation of cancelling the abort -- ICEBERG_LOG_FATAL always terminates; if
+/// the handler itself does not exit the process, std::abort() still runs after it.
+using FatalHandler =
+    std::function<void(const std::source_location&, std::string_view message)>;
+
+/// \brief Install (or clear, with nullptr) the process-global fatal handler.
+///
+/// Thread-safe. Intended to be set once at startup. Replaces any previous handler.
+ICEBERG_EXPORT void SetFatalHandler(FatalHandler handler);
+
+/// \brief Return the installed fatal handler (empty if none). Used by the fatal
+/// logging path; thread-safe.
+ICEBERG_EXPORT FatalHandler GetFatalHandler();
+
 /// \brief Bind a logger for the current thread until this object leaves scope.
 ///
 /// The default logging path on this thread -- CurrentLogger(), Log(level, ...),

src/iceberg/test/macros_test.cc

@@ -17,7 +17,10 @@
  * under the License.
  */
 
+#include <iostream>
 #include <memory>
+#include <source_location>
+#include <string_view>
 
 #include <gtest/gtest.h>
 
@@ -162,4 +165,43 @@ TEST(MacrosDeathTest, FatalRoutesThroughScopedLogger) {
       "scopedfatal 9");
 }
 
+// A registered FatalHandler runs on the fatal path (after emit+flush) and receives
+// the formatted message; the process still aborts afterwards.
+TEST(MacrosDeathTest, FatalHandlerRunsWithFormattedMessageBeforeAbort) {
+  EXPECT_DEATH(
+      {
+        SetFatalHandler([](const std::source_location&, std::string_view message) {
+          std::cerr << "HANDLER[" << message << "]\n";
+        });
+        ICEBERG_LOG_FATAL("boom {}", 42);
+      },
+      "HANDLER\\[boom 42\\]");
+}
+
+// The handler receives the caller's source location.
+TEST(MacrosDeathTest, FatalHandlerReceivesCallSiteLocation) {
+  EXPECT_DEATH(
+      {
+        SetFatalHandler([](const std::source_location& loc, std::string_view) {
+          std::cerr << "LOC:" << (loc.line() > 0 ? "ok" : "bad") << "\n";
+        });
+        ICEBERG_LOG_FATAL("x");
+      },
+      "LOC:ok");
+}
+
+// The handler is a termination hook independent of log filtering: it still fires
+// (with the formatted message) when the fatal record itself is suppressed.
+TEST(MacrosDeathTest, FatalHandlerRunsEvenWhenRecordSuppressed) {
+  EXPECT_DEATH(
+      {
+        SetDefaultLevel(LogLevel::kOff);
+        SetFatalHandler([](const std::source_location&, std::string_view message) {
+          std::cerr << "H[" << message << "]\n";
+        });
+        ICEBERG_LOG_FATAL("suppressed {}", 7);
+      },
+      "H\\[suppressed 7\\]");
+}
+
 }  // namespace iceberg