Add the Logger interface and the process-wide default logger

Second of the logging stack. This defines what a logger is and where the rest of
the code finds one, with no concrete backend yet.

Logger is a small abstract interface: ShouldLog to test a level, Log to emit an
already-formatted record, SetLevel/level, Flush, and a shared no-op instance.
Records are passed as LogMessage, which owns its formatted text (so a sink may
safely hold onto it) and carries the source location plus a reserved slot for
structured key/values we may add later. The interface spells out two rules for
implementations: never call back into logging from inside Log/Flush, and keep
level() a true lower bound for ShouldLog.

There is also one default logger per process, designed to be cheap to reach on
the logging path: a lock-free atomic level check drops disabled messages
outright, and when a message does need logging the current logger comes from a
thread-local cache that only refreshes when the default actually changes, so the
steady state has no lock or reference-count traffic. SetDefaultLogger and
SetDefaultLevel swap it safely under a mutex. The seed default is the no-op
logger; CerrLogger and the spdlog backend arrive in later PRs.

Also adds the build-generated, .cc-only config header used later to pick the
backend, and tests for the interface and the default-logger lifecycle.

Co-authored-by: Isaac

Author: kamcheungting-db

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

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/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

src/iceberg/logging/logger.h

@@ -0,0 +1,143 @@
+/*
+ * 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/logger.h
+/// \brief Pluggable logging interface and the process-global default logger.
+///
+/// This header is backend-agnostic: it never includes the build-generated
+/// backend configuration header and never references the spdlog feature macro,
+/// so consumers see one stable API regardless of how the backend was configured.
+
+#include <memory>
+#include <source_location>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+#include <vector>
+
+#include "iceberg/iceberg_export.h"
+#include "iceberg/logging/log_level.h"
+#include "iceberg/result.h"
+
+namespace iceberg {
+
+/// \brief A structured key/value attribute attached to a log record.
+///
+/// Both key and value are owned so a sink may retain the record safely.
+/// Unused in v1; reserved so structured logging can be added without an ABI
+/// break to LogMessage.
+struct LogAttribute {
+  std::string key;
+  std::string value;
+};
+
+/// \brief A single log record handed to a Logger.
+///
+/// The formatted message is owned (moved in by the logging macros), so a sink
+/// may safely retain the record beyond the Log() call. The member set must not
+/// depend on the build's logging backend (the spdlog backend never appears here).
+struct LogMessage {
+  LogLevel level;
+  std::string message;
+  std::source_location location;
+  std::vector<LogAttribute> attributes;
+};
+
+/// \brief Pluggable logging sink.
+///
+/// Implementations must be thread-safe and must not throw. They must also obey:
+///   - No reentrancy: Log()/Flush() must not call the logging macros or
+///     GetDefaultLogger() (UB -- deadlock with mutex-based sinks).
+///   - Lower-bound level: ShouldLog(l) must imply l >= level(), i.e. level()
+///     summarizes ShouldLog(), because the global fast-path gate reflects only
+///     level(). A logger needing finer logic must report its most permissive
+///     threshold from level().
+class ICEBERG_EXPORT Logger {
+ public:
+  virtual ~Logger() = default;
+
+  /// \brief Property-based setup, called by Loggers::Load() before first use.
+  ///
+  /// The default is a no-op. Recognized properties include "level" (parsed via
+  /// LogLevelFromString) and, for formatting sinks, "pattern".
+  virtual Status Initialize(
+      [[maybe_unused]] const std::unordered_map<std::string, std::string>& properties) {
+    return {};
+  }
+
+  /// \brief Cheap check whether a record at \p level would be emitted.
+  virtual bool ShouldLog(LogLevel level) const = 0;
+
+  /// \brief Emit one (already-formatted) record, taking ownership. Must not throw.
+  virtual void Log(LogMessage&& message) noexcept = 0;
+
+  /// \brief Set the minimum level this logger emits.
+  virtual void SetLevel(LogLevel level) = 0;
+
+  /// \brief Return the minimum level this logger emits.
+  virtual LogLevel level() const = 0;
+
+  /// \brief Flush any buffered output. Must not throw; best-effort on the fatal path.
+  virtual void Flush() noexcept {}
+
+  /// \brief Return true if this logger is a no-op.
+  virtual bool IsNoop() const { return false; }
+
+  /// \brief Return a shared, immortal no-op logger singleton.
+  static std::shared_ptr<Logger> Noop();
+};
+
+/// \brief Return the process-global default logger (never null).
+///
+/// Off the hot path -- acquires the slot lock and returns an owning copy. The
+/// logging macros use the cheaper internal hot-path accessor instead.
+ICEBERG_EXPORT std::shared_ptr<Logger> GetDefaultLogger();
+
+/// \brief Install a new process-global default logger.
+///
+/// A null argument installs the no-op logger. Thread-safe; intended for
+/// occasional (configuration-time) use rather than the hot path.
+ICEBERG_EXPORT void SetDefaultLogger(std::shared_ptr<Logger> logger);
+
+/// \brief Set the minimum level of the current default logger.
+///
+/// Updates both the logger and the lock-free fast-path gate atomically.
+ICEBERG_EXPORT void SetDefaultLevel(LogLevel level);
+
+namespace detail {
+
+/// \brief Lock-free read of the cached effective minimum level.
+///
+/// This is a non-authoritative lower-bound early-out: it may admit extra calls
+/// through to the authoritative Logger::ShouldLog, but never wrongly rejects.
+ICEBERG_EXPORT LogLevel EffectiveLevel() noexcept;
+
+/// \brief Hot-path accessor for the default logger.
+///
+/// Returns a reference to a thread-local cached shared_ptr that is refreshed
+/// only when the default logger has changed (no lock / no refcount churn in
+/// steady state). The reference is valid for the duration of the calling
+/// statement.
+ICEBERG_EXPORT const std::shared_ptr<Logger>& CurrentLogger() noexcept;
+
+}  // namespace detail
+
+}  // namespace iceberg

src/iceberg/logging/meson.build

@@ -0,0 +1,28 @@
+# 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.
+
+# Generate the .cc-only logging backend config header. The meson build always
+# links spdlog, so ICEBERG_HAS_SPDLOG is always defined here. Generated into
+# build/src/iceberg/logging/config.h (resolved via include_directories('..'),
+# which exposes both the source and build trees); not installed.
+logging_config_data = configuration_data()
+logging_config_data.set('ICEBERG_HAS_SPDLOG', 1)
+configure_file(output: 'config.h', configuration: logging_config_data)
+
+# Public logging headers. The build-generated config.h and the internal
+# SpdLogger header are intentionally NOT installed.
+install_headers(['log_level.h', 'logger.h'], subdir: 'iceberg/logging')

src/iceberg/meson.build

@@ -38,6 +38,10 @@ configure_file(
     install_dir: get_option('includedir') / 'iceberg',
 )
 
+# Generate iceberg/logging/config.h (must precede the library() that compiles
+# the logging sources which include it).
+subdir('logging')
+
 iceberg_include_dir = include_directories('..')
 iceberg_sources = files(
     'arrow_c_data_guard_internal.cc',
@@ -66,6 +70,7 @@ iceberg_sources = files(
     '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',

src/iceberg/test/CMakeLists.txt

@@ -101,7 +101,7 @@ add_iceberg_test(table_test
                  table_test.cc
                  table_update_test.cc)
 
-add_iceberg_test(logging_test SOURCES log_level_test.cc)
+add_iceberg_test(logging_test SOURCES log_level_test.cc logger_test.cc)
 
 add_iceberg_test(expression_test
                  SOURCES