feat(logging): add Loggers registry (6/6)

CMakeLists.txt

@@ -55,6 +55,7 @@ option(ICEBERG_SQL_MYSQL "Build the MySQL connector for the SQL catalog" OFF)
 option(ICEBERG_S3 "Build with S3 support" OFF)
 option(ICEBERG_SIGV4 "Build with SigV4 support" OFF)
 option(ICEBERG_BUNDLE_AWSSDK "Bundle AWS SDK for S3/SigV4 support" ON)
+option(ICEBERG_SPDLOG "Use spdlog as the default logging backend" ON)
 option(ICEBERG_ENABLE_ASAN "Enable Address Sanitizer" OFF)
 option(ICEBERG_ENABLE_UBSAN "Enable Undefined Behavior Sanitizer" OFF)
 

cmake_modules/IcebergThirdpartyToolchain.cmake

@@ -720,7 +720,9 @@ resolve_zlib_dependency()
 resolve_nanoarrow_dependency()
 resolve_croaring_dependency()
 resolve_nlohmann_json_dependency()
-resolve_spdlog_dependency()
+if(ICEBERG_SPDLOG)
+  resolve_spdlog_dependency()
+endif()
 
 if(ICEBERG_S3 OR ICEBERG_SIGV4)
   if(ICEBERG_SIGV4 AND NOT ICEBERG_BUILD_REST)

meson.build

@@ -31,7 +31,9 @@ project(
 )
 
 cpp = meson.get_compiler('cpp')
-args = cpp.get_supported_arguments(['/bigobj'])
+# /Zc:preprocessor: MSVC's conforming preprocessor, required for the __VA_OPT__
+# used by the logging macros. get_supported_arguments drops it on non-MSVC.
+args = cpp.get_supported_arguments(['/bigobj', '/Zc:preprocessor'])
 add_project_arguments(args, language: 'cpp')
 
 subdir('src')

src/iceberg/CMakeLists.txt

@@ -17,6 +17,18 @@
 
 set(ICEBERG_INCLUDES "$<BUILD_INTERFACE:${PROJECT_BINARY_DIR}/src>"
                      "$<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/src>")
+
+# Generate the logging backend config header. ALWAYS generated (not gated by
+# ICEBERG_SPDLOG) so logging/logger.cc can include it in both ON and OFF builds;
+# only the definedness of ICEBERG_HAS_SPDLOG varies. Generated into the build
+# tree (already on ICEBERG_INCLUDES), included as "iceberg/logging/config.h", and
+# NOT installed (it must never appear in a public/installed header).
+if(ICEBERG_SPDLOG)
+  set(ICEBERG_HAS_SPDLOG ON)
+endif()
+configure_file("${CMAKE_CURRENT_SOURCE_DIR}/logging/config.h.in"
+               "${CMAKE_CURRENT_BINARY_DIR}/logging/config.h")
+
 set(ICEBERG_SOURCES
     arrow_c_data_util.cc
     arrow_c_data_guard_internal.cc
@@ -47,6 +59,9 @@ set(ICEBERG_SOURCES
     inheritable_metadata.cc
     json_serde.cc
     location_provider.cc
+    logging/cerr_logger.cc
+    logging/logger.cc
+    logging/loggers.cc
     manifest/manifest_adapter.cc
     manifest/manifest_entry.cc
     manifest/manifest_filter_manager.cc
@@ -142,24 +157,34 @@ list(APPEND
      ICEBERG_STATIC_BUILD_INTERFACE_LIBS
      "$<IF:$<BOOL:${NANOARROW_VENDORED}>,nanoarrow::nanoarrow_static,$<IF:$<TARGET_EXISTS:nanoarrow::nanoarrow_static>,nanoarrow::nanoarrow_static,nanoarrow::nanoarrow_shared>>"
      nlohmann_json::nlohmann_json
-     spdlog::spdlog
      ZLIB::ZLIB)
 list(APPEND
      ICEBERG_SHARED_BUILD_INTERFACE_LIBS
      "$<IF:$<BOOL:${NANOARROW_VENDORED}>,nanoarrow::nanoarrow_static,$<IF:$<TARGET_EXISTS:nanoarrow::nanoarrow_shared>,nanoarrow::nanoarrow_shared,nanoarrow::nanoarrow_static>>"
      nlohmann_json::nlohmann_json
-     spdlog::spdlog
      ZLIB::ZLIB)
 list(APPEND
      ICEBERG_STATIC_INSTALL_INTERFACE_LIBS
      "$<IF:$<BOOL:${NANOARROW_VENDORED}>,iceberg::nanoarrow_static,$<IF:$<TARGET_EXISTS:nanoarrow::nanoarrow_static>,nanoarrow::nanoarrow_static,nanoarrow::nanoarrow_shared>>"
      "$<IF:$<BOOL:${NLOHMANN_JSON_VENDORED}>,iceberg::nlohmann_json,$<IF:$<TARGET_EXISTS:nlohmann_json::nlohmann_json>,nlohmann_json::nlohmann_json,nlohmann_json::nlohmann_json>>"
-     "$<IF:$<BOOL:${SPDLOG_VENDORED}>,iceberg::spdlog,spdlog::spdlog>")
+)
 list(APPEND
      ICEBERG_SHARED_INSTALL_INTERFACE_LIBS
      "$<IF:$<BOOL:${NANOARROW_VENDORED}>,iceberg::nanoarrow_static,$<IF:$<TARGET_EXISTS:nanoarrow::nanoarrow_shared>,nanoarrow::nanoarrow_shared,nanoarrow::nanoarrow_static>>"
      "$<IF:$<BOOL:${NLOHMANN_JSON_VENDORED}>,iceberg::nlohmann_json,$<IF:$<TARGET_EXISTS:nlohmann_json::nlohmann_json>,nlohmann_json::nlohmann_json,nlohmann_json::nlohmann_json>>"
-     "$<IF:$<BOOL:${SPDLOG_VENDORED}>,iceberg::spdlog,spdlog::spdlog>")
+)
+
+# spdlog backend: linked and compiled only when ICEBERG_SPDLOG is ON. When OFF,
+# the core library has no spdlog dependency and CerrLogger is the default sink.
+if(ICEBERG_SPDLOG)
+  list(APPEND ICEBERG_SOURCES logging/internal/spdlog_logger.cc)
+  list(APPEND ICEBERG_STATIC_BUILD_INTERFACE_LIBS spdlog::spdlog)
+  list(APPEND ICEBERG_SHARED_BUILD_INTERFACE_LIBS spdlog::spdlog)
+  list(APPEND ICEBERG_STATIC_INSTALL_INTERFACE_LIBS
+       "$<IF:$<BOOL:${SPDLOG_VENDORED}>,iceberg::spdlog,spdlog::spdlog>")
+  list(APPEND ICEBERG_SHARED_INSTALL_INTERFACE_LIBS
+       "$<IF:$<BOOL:${SPDLOG_VENDORED}>,iceberg::spdlog,spdlog::spdlog>")
+endif()
 
 add_iceberg_lib(iceberg
                 SOURCES

src/iceberg/logging/cerr_logger.cc

@@ -0,0 +1,105 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+#include "iceberg/logging/cerr_logger.h"
+
+#include <chrono>
+#include <cstdint>
+#include <format>
+#include <iostream>
+#include <mutex>
+#include <string>
+#include <string_view>
+
+#if defined(_WIN32)
+#  include <windows.h>
+#elif defined(__APPLE__)
+#  include <pthread.h>
+#else
+#  include <unistd.h>
+
+#  include <sys/syscall.h>
+#endif
+
+namespace iceberg {
+
+namespace {
+
+/// \brief OS-native thread id, cached per thread to avoid a syscall per log.
+///
+/// Matches the cross-process-correlatable id used by spdlog/glog (not the opaque
+/// std::thread::id), and avoids the std::formatter<std::thread::id> (P2693)
+/// minimum-toolchain dependency.
+uint64_t OsThreadId() noexcept {
+  static thread_local uint64_t tid = []() -> uint64_t {
+#if defined(_WIN32)
+    return static_cast<uint64_t>(::GetCurrentThreadId());
+#elif defined(__APPLE__)
+    uint64_t id = 0;
+    pthread_threadid_np(nullptr, &id);
+    return id;
+#else
+    return static_cast<uint64_t>(::syscall(SYS_gettid));
+#endif
+  }();
+  return tid;
+}
+
+/// \brief Trailing path component of a source file path.
+std::string_view Basename(std::string_view path) noexcept {
+  auto pos = path.find_last_of("/\\");
+  return pos == std::string_view::npos ? path : path.substr(pos + 1);
+}
+
+/// \brief Format a record into a single newline-terminated line.
+std::string FormatLine(const LogMessage& message) {
+  auto now =
+      std::chrono::floor<std::chrono::milliseconds>(std::chrono::system_clock::now());
+  return std::format("{:%Y-%m-%dT%H:%M:%S}Z {} [{}] {}:{}] {}\n", now,
+                     ToString(message.level), OsThreadId(),
+                     Basename(message.location.file_name()), message.location.line(),
+                     message.message);
+}
+
+}  // namespace
+
+void CerrLogger::Log(LogMessage&& message) noexcept {
+  try {
+    std::string line = FormatLine(message);
+    std::lock_guard<std::mutex> lock(mutex_);
+    std::cerr << line;
+  } catch (...) {
+    // Logging must never throw. Best-effort fallback, swallow any failure.
+    try {
+      std::lock_guard<std::mutex> lock(mutex_);
+      std::cerr << "<fmt error>\n";
+    } catch (...) {
+    }
+  }
+}
+
+void CerrLogger::Flush() noexcept {
+  try {
+    std::lock_guard<std::mutex> lock(mutex_);
+    std::cerr.flush();
+  } catch (...) {
+  }
+}
+
+}  // namespace iceberg

src/iceberg/logging/cerr_logger.h

@@ -0,0 +1,59 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+#pragma once
+
+/// \file iceberg/logging/cerr_logger.h
+/// \brief Always-available std::cerr logging backend.
+
+#include <atomic>
+#include <mutex>
+
+#include "iceberg/iceberg_export.h"
+#include "iceberg/logging/log_level.h"
+#include "iceberg/logging/logger.h"
+
+namespace iceberg {
+
+/// \brief Logger that writes one line per record to std::cerr.
+///
+/// Line layout: `YYYY-MM-DDThh:mm:ss.mmmZ LEVEL [tid] file:line] message`.
+/// The minimum level is held in a lock-free atomic; a mutex serializes the
+/// whole-line write so concurrent records never interleave. Pure standard
+/// library -- always compiled, regardless of ICEBERG_SPDLOG.
+class ICEBERG_EXPORT CerrLogger : public Logger {
+ public:
+  explicit CerrLogger(LogLevel level = LogLevel::kInfo) : level_(level) {}
+
+  bool ShouldLog(LogLevel level) const override {
+    return level >= level_.load(std::memory_order_relaxed);
+  }
+  void Log(LogMessage&& message) noexcept override;
+  void SetLevel(LogLevel level) override {
+    level_.store(level, std::memory_order_relaxed);
+  }
+  LogLevel level() const override { return level_.load(std::memory_order_relaxed); }
+  void Flush() noexcept override;
+
+ private:
+  std::atomic<LogLevel> level_;
+  std::mutex mutex_;
+};
+
+}  // namespace iceberg

src/iceberg/logging/config.h.in

@@ -0,0 +1,30 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+#pragma once
+
+// Internal, build-generated configuration for the logging backend.
+// This header is NOT installed and must only be included from .cc files
+// (logger.cc, internal/spdlog_logger.cc) -- never from a public header.
+//
+// ICEBERG_HAS_SPDLOG is defined when the project is built with -DICEBERG_SPDLOG=ON
+// and left undefined otherwise. Always test it with #ifdef / #ifndef, never #if
+// (it carries no value).
+
+#cmakedefine ICEBERG_HAS_SPDLOG

src/iceberg/logging/internal/spdlog_logger.cc

@@ -0,0 +1,103 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+#include "iceberg/logging/internal/spdlog_logger.h"
+
+#ifdef ICEBERG_HAS_SPDLOG
+
+#  include <memory>
+#  include <string>
+#  include <unordered_map>
+#  include <utility>
+
+#  include <spdlog/common.h>
+#  include <spdlog/sinks/stdout_color_sinks.h>
+
+namespace iceberg::internal {
+
+namespace {
+
+spdlog::level::level_enum ToSpdLevel(LogLevel level) noexcept {
+  switch (level) {
+    case LogLevel::kTrace:
+      return spdlog::level::trace;
+    case LogLevel::kDebug:
+      return spdlog::level::debug;
+    case LogLevel::kInfo:
+      return spdlog::level::info;
+    case LogLevel::kWarn:
+      return spdlog::level::warn;
+    case LogLevel::kError:
+      return spdlog::level::err;
+    case LogLevel::kCritical:
+    case LogLevel::kFatal:
+      // spdlog has no "fatal"; the process abort is owned by the macro layer.
+      return spdlog::level::critical;
+    case LogLevel::kOff:
+      return spdlog::level::off;
+  }
+  return spdlog::level::off;
+}
+
+}  // namespace
+
+SpdLogger::SpdLogger(LogLevel level)
+    : SpdLogger(std::make_shared<spdlog::logger>(
+                    "iceberg", std::make_shared<spdlog::sinks::stderr_color_sink_mt>()),
+                level) {}
+
+Status SpdLogger::Initialize(
+    const std::unordered_map<std::string, std::string>& properties) {
+  if (auto it = properties.find(std::string(kPatternProperty)); it != properties.end()) {
+    logger_->set_pattern(it->second);
+  }
+  // Apply "level" via the base implementation.
+  return Logger::Initialize(properties);
+}
+
+SpdLogger::SpdLogger(std::shared_ptr<spdlog::logger> logger, LogLevel level)
+    : logger_(std::move(logger)), level_(level) {
+  if (logger_) {
+    logger_->set_level(spdlog::level::trace);  // filtering is done by ShouldLog
+  }
+}
+
+void SpdLogger::Log(LogMessage&& message) noexcept {
+  try {
+    spdlog::source_loc loc{message.location.file_name(),
+                           static_cast<int>(message.location.line()),
+                           message.location.function_name()};
+    // Pass the pre-formatted text as an argument ("{}") so any braces in the
+    // message are not re-interpreted as a format string.
+    logger_->log(loc, ToSpdLevel(message.level), "{}", message.message);
+  } catch (...) {
+    // Logging must never throw.
+  }
+}
+
+void SpdLogger::Flush() noexcept {
+  try {
+    logger_->flush();
+  } catch (...) {
+  }
+}
+
+}  // namespace iceberg::internal
+
+#endif  // ICEBERG_HAS_SPDLOG