feat(logging): add Logger interface and default logger (2/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)
 

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,7 @@ set(ICEBERG_SOURCES
     inheritable_metadata.cc
     json_serde.cc
     location_provider.cc
+    logging/logger.cc
     manifest/manifest_adapter.cc
     manifest/manifest_entry.cc
     manifest/manifest_filter_manager.cc
@@ -239,6 +252,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/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/log_level.h

@@ -0,0 +1,91 @@
+/*
+ * 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/log_level.h
+/// \brief Severity levels for the logging system.
+
+#include <string_view>
+#include <utility>
+
+#include "iceberg/iceberg_export.h"
+#include "iceberg/result.h"
+#include "iceberg/util/string_util.h"
+
+namespace iceberg {
+
+/// \brief Logging severity level, ordered from most to least verbose.
+///
+/// Levels are ordered so that `level >= threshold` is the enabled test.
+/// `kOff` is the maximum sentinel: as a threshold it disables all emission
+/// (it is never the level of an actual message).
+enum class LogLevel {
+  kTrace,
+  kDebug,
+  kInfo,
+  kWarn,
+  kError,
+  kCritical,
+  kFatal,
+  kOff,
+};
+
+/// \brief String representation of a LogLevel.
+ICEBERG_EXPORT constexpr std::string_view ToString(LogLevel level) noexcept {
+  switch (level) {
+    case LogLevel::kTrace:
+      return "trace";
+    case LogLevel::kDebug:
+      return "debug";
+    case LogLevel::kInfo:
+      return "info";
+    case LogLevel::kWarn:
+      return "warn";
+    case LogLevel::kError:
+      return "error";
+    case LogLevel::kCritical:
+      return "critical";
+    case LogLevel::kFatal:
+      return "fatal";
+    case LogLevel::kOff:
+      return "off";
+  }
+  std::unreachable();
+}
+
+/// \brief Parse a LogLevel from a string (case-insensitive).
+///
+/// \param s The string to parse ("trace", "debug", "info", "warn", "error",
+///   "critical", "fatal", or "off").
+/// \return The LogLevel, or an InvalidArgument error if unrecognized.
+ICEBERG_EXPORT inline Result<LogLevel> LogLevelFromString(std::string_view s) {
+  auto level = StringUtils::ToLower(s);
+  if (level == "trace") return LogLevel::kTrace;
+  if (level == "debug") return LogLevel::kDebug;
+  if (level == "info") return LogLevel::kInfo;
+  if (level == "warn") return LogLevel::kWarn;
+  if (level == "error") return LogLevel::kError;
+  if (level == "critical") return LogLevel::kCritical;
+  if (level == "fatal") return LogLevel::kFatal;
+  if (level == "off") return LogLevel::kOff;
+  return InvalidArgument("Invalid log level: {}", s);
+}
+
+}  // namespace iceberg

src/iceberg/logging/logger.cc

@@ -0,0 +1,126 @@
+/*
+ * 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/logger.h"
+
+#include <atomic>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <utility>
+
+namespace iceberg {
+
+namespace {
+
+/// \brief Logger that drops every record.
+class NoopLogger final : public Logger {
+ public:
+  bool ShouldLog(LogLevel /*level*/) const override { return false; }
+  void Log(LogMessage&& /*message*/) noexcept override {}
+  void SetLevel(LogLevel /*level*/) override {}
+  LogLevel level() const override { return LogLevel::kOff; }
+  bool IsNoop() const override { return true; }
+};
+
+/// \brief Construct the process default logger for this build configuration.
+///
+/// Block 2 defaults to the no-op logger; Block 3 switches this to CerrLogger and
+/// Block 5 wraps the selection in `#ifdef ICEBERG_HAS_SPDLOG` to prefer SpdLogger.
+std::shared_ptr<Logger> MakeDefaultLogger() { return Logger::Noop(); }
+
+/// \brief The process-global default-logger slot.
+struct DefaultSlot {
+  std::mutex mtx;
+  std::shared_ptr<Logger> logger;
+  // Seeded to 1 so a fresh thread (tls_gen == 0) always refreshes on first use.
+  std::atomic<uint64_t> gen{1};
+
+  DefaultSlot() : logger(MakeDefaultLogger()) {}
+};
+
+/// \brief Immortal (leaked, hence reachable -> LSan-clean) accessor for the slot.
+DefaultSlot& Slot() {
+  static auto* slot = new DefaultSlot();
+  return *slot;
+}
+
+/// \brief Cached effective minimum level (lock-free fast-path gate).
+///
+/// Constant-initialized permissive (kTrace); seeded to the default logger's
+/// level() on first slot use and on every Set*. As a lower bound it may only
+/// admit extra calls through to the authoritative Logger::ShouldLog.
+std::atomic<LogLevel> g_effective_level{LogLevel::kTrace};
+
+}  // namespace
+
+std::shared_ptr<Logger> Logger::Noop() {
+  // Intentionally leaked: reachable via the function-local static (LSan-clean)
+  // and never destroyed, so logging during static teardown stays safe.
+  static auto* instance = new std::shared_ptr<Logger>(std::make_shared<NoopLogger>());
+  return *instance;
+}
+
+std::shared_ptr<Logger> GetDefaultLogger() {
+  DefaultSlot& slot = Slot();
+  std::lock_guard<std::mutex> lock(slot.mtx);
+  return slot.logger;
+}
+
+void SetDefaultLogger(std::shared_ptr<Logger> logger) {
+  if (!logger) {
+    logger = Logger::Noop();
+  }
+  DefaultSlot& slot = Slot();
+  std::lock_guard<std::mutex> lock(slot.mtx);
+  g_effective_level.store(logger->level(), std::memory_order_relaxed);
+  slot.logger = std::move(logger);
+  // Publish the swap; the mutex provides the happens-before, gen is a detector.
+  slot.gen.fetch_add(1, std::memory_order_relaxed);
+}
+
+void SetDefaultLevel(LogLevel level) {
+  DefaultSlot& slot = Slot();
+  std::lock_guard<std::mutex> lock(slot.mtx);
+  slot.logger->SetLevel(level);
+  g_effective_level.store(level, std::memory_order_relaxed);
+}
+
+namespace detail {
+
+LogLevel EffectiveLevel() noexcept {
+  return g_effective_level.load(std::memory_order_relaxed);
+}
+
+const std::shared_ptr<Logger>& CurrentLogger() noexcept {
+  static thread_local std::shared_ptr<Logger> tls;
+  static thread_local uint64_t tls_gen = 0;
+  DefaultSlot& slot = Slot();
+  uint64_t current = slot.gen.load(std::memory_order_relaxed);
+  if (current != tls_gen) {
+    std::lock_guard<std::mutex> lock(slot.mtx);
+    tls = slot.logger;
+    tls_gen = current;
+  }
+  return tls;
+}
+
+}  // namespace detail
+
+}  // namespace iceberg