feat(logging): add spdlog backend behind ICEBERG_SPDLOG (5/6)

CMakeLists.txt

@@ -53,6 +53,7 @@ option(ICEBERG_SQL_SQLITE "Build the SQLite connector for the SQL catalog" OFF)
 option(ICEBERG_SQL_POSTGRESQL "Build the PostgreSQL connector for the SQL catalog" OFF)
 option(ICEBERG_SQL_MYSQL "Build the MySQL connector for the SQL catalog" OFF)
 option(ICEBERG_S3 "Build with S3 support" OFF)
+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)
 

README.md

@@ -152,6 +152,7 @@ If you experience network issues when downloading dependencies, you can customiz
 - `ICEBERG_NANOARROW_URL`: Nanoarrow tarball URL
 - `ICEBERG_CROARING_URL`: CRoaring tarball URL
 - `ICEBERG_NLOHMANN_JSON_URL`: nlohmann-json tarball URL
+- `ICEBERG_SPDLOG_URL`: spdlog tarball URL
 - `ICEBERG_CPR_URL`: cpr tarball URL
 
 Example:

cmake_modules/IcebergThirdpartyToolchain.cmake

@@ -31,6 +31,7 @@ set(ICEBERG_ARROW_INSTALL_INTERFACE_LIBS)
 # ICEBERG_NANOARROW_URL      - Nanoarrow tarball URL
 # ICEBERG_CROARING_URL       - CRoaring tarball URL
 # ICEBERG_NLOHMANN_JSON_URL  - nlohmann-json tarball URL
+# ICEBERG_SPDLOG_URL         - spdlog tarball URL
 # ICEBERG_CPR_URL            - cpr tarball URL
 #
 # Example usage:
@@ -437,6 +438,61 @@ function(resolve_nlohmann_json_dependency)
       PARENT_SCOPE)
 endfunction()
 
+# ----------------------------------------------------------------------
+# spdlog
+
+function(resolve_spdlog_dependency)
+  prepare_fetchcontent()
+
+  find_package(Threads REQUIRED)
+
+  set(SPDLOG_USE_STD_FORMAT
+      ON
+      CACHE BOOL "" FORCE)
+  set(SPDLOG_BUILD_PIC
+      ON
+      CACHE BOOL "" FORCE)
+
+  if(DEFINED ENV{ICEBERG_SPDLOG_URL})
+    set(SPDLOG_URL "$ENV{ICEBERG_SPDLOG_URL}")
+  else()
+    set(SPDLOG_URL "https://github.com/gabime/spdlog/archive/refs/tags/v1.15.3.tar.gz")
+  endif()
+
+  fetchcontent_declare(spdlog
+                       ${FC_DECLARE_COMMON_OPTIONS}
+                       URL ${SPDLOG_URL}
+                           FIND_PACKAGE_ARGS
+                           NAMES
+                           spdlog
+                           CONFIG)
+  fetchcontent_makeavailable(spdlog)
+
+  if(spdlog_SOURCE_DIR)
+    set_target_properties(spdlog PROPERTIES OUTPUT_NAME "iceberg_vendored_spdlog"
+                                            POSITION_INDEPENDENT_CODE ON)
+    target_link_libraries(spdlog INTERFACE Threads::Threads)
+    install(TARGETS spdlog
+            EXPORT iceberg_targets
+            RUNTIME DESTINATION "${ICEBERG_INSTALL_BINDIR}"
+            ARCHIVE DESTINATION "${ICEBERG_INSTALL_LIBDIR}"
+            LIBRARY DESTINATION "${ICEBERG_INSTALL_LIBDIR}")
+    set(SPDLOG_VENDORED TRUE)
+  else()
+    set(SPDLOG_VENDORED FALSE)
+    list(APPEND ICEBERG_SYSTEM_DEPENDENCIES spdlog)
+  endif()
+
+  list(APPEND ICEBERG_SYSTEM_DEPENDENCIES Threads)
+
+  set(ICEBERG_SYSTEM_DEPENDENCIES
+      ${ICEBERG_SYSTEM_DEPENDENCIES}
+      PARENT_SCOPE)
+  set(SPDLOG_VENDORED
+      ${SPDLOG_VENDORED}
+      PARENT_SCOPE)
+endfunction()
+
 # ----------------------------------------------------------------------
 # zlib
 
@@ -614,6 +670,9 @@ resolve_zlib_dependency()
 resolve_nanoarrow_dependency()
 resolve_croaring_dependency()
 resolve_nlohmann_json_dependency()
+if(ICEBERG_SPDLOG)
+  resolve_spdlog_dependency()
+endif()
 
 if(ICEBERG_BUILD_BUNDLE)
   resolve_arrow_dependency()

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
@@ -44,6 +56,8 @@ set(ICEBERG_SOURCES
     inheritable_metadata.cc
     json_serde.cc
     location_provider.cc
+    logging/cerr_logger.cc
+    logging/logger.cc
     manifest/manifest_adapter.cc
     manifest/manifest_entry.cc
     manifest/manifest_filter_manager.cc
@@ -148,13 +162,23 @@ list(APPEND
 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:${NLOHMANN_JSON_VENDORED}>,iceberg::nlohmann_json,$<IF:$<TARGET_EXISTS:nlohmann_json::nlohmann_json>,nlohmann_json::nlohmann_json,nlohmann_json::nlohmann_json>>")
 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:${NLOHMANN_JSON_VENDORED}>,iceberg::nlohmann_json,$<IF:$<TARGET_EXISTS:nlohmann_json::nlohmann_json>,nlohmann_json::nlohmann_json,nlohmann_json::nlohmann_json>>")
+
+# 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
@@ -237,6 +261,7 @@ add_subdirectory(row)
 add_subdirectory(update)
 add_subdirectory(util)
 add_subdirectory(metrics)
+add_subdirectory(logging)
 
 if(ICEBERG_BUILD_BUNDLE)
   set(ICEBERG_BUNDLE_SOURCES

src/iceberg/logging/CMakeLists.txt

@@ -0,0 +1,18 @@
+# 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.
+
+iceberg_install_all_headers(iceberg/logging)

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 << "<log format 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