You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iceberg.apache.org by ga...@apache.org on 2026/06/24 15:43:53 UTC

(iceberg-cpp) branch main updated: feat(logging): add CerrLogger std::cerr backend (#724)

This is an automated email from the ASF dual-hosted git repository.

wgtmac pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-cpp.git


The following commit(s) were added to refs/heads/main by this push:
     new 411c0f8d feat(logging): add CerrLogger std::cerr backend (#724)
411c0f8d is described below

commit 411c0f8ddc2abe95140552cb9d1cf363d541b0af
Author: kamcheungting-db <91...@users.noreply.github.com>
AuthorDate: Wed Jun 24 08:43:48 2026 -0700

    feat(logging): add CerrLogger std::cerr backend (#724)
    
    Part 3 of the logging stack — now based on `main` (#723 merged). Adds
    the first concrete sink: a dependency-free `std::cerr` logger, also the
    default backend when spdlog is off.
    
    **What's here**
    - `CerrLogger` writes one line per record: `YYYY-MM-DDThh:mm:ss.mmmZ
    LEVEL [tid] [file:line] message`.
    - UTC millisecond timestamps, OS-native cached thread id (extracted to
    `util/thread_util.h`), lock-free level check, and a whole-line mutex so
    concurrent records never interleave.
    - Pure standard library, always available. `Log`/`Flush` never throw.
    Inherits the base `Initialize("level")`; `pattern` is ignored (fixed
    layout; only the spdlog backend honors `pattern`).
    
    **Tests** (`cerr_logger_test`): level filtering, the fixed line layout
    incl. the `.mmm` field and `[file:line]`, inherited `Initialize`,
    `Flush`, never-throw when the sink itself throws, and concurrent-write
    non-interleaving. Built/run under clang-libc++; ASan + TSan clean.
    
    This pull request and its description were written by Isaac.
---
 ci/scripts/build_example.sh             |   6 +-
 src/iceberg/CMakeLists.txt              |   2 +
 src/iceberg/logging/cerr_logger.cc      |  77 ++++++++++++
 src/iceberg/logging/cerr_logger.h       |  61 ++++++++++
 src/iceberg/logging/logger.cc           |   9 +-
 src/iceberg/logging/logger.h            |   8 +-
 src/iceberg/logging/meson.build         |   5 +-
 src/iceberg/meson.build                 |   2 +
 src/iceberg/test/CMakeLists.txt         |   6 +-
 src/iceberg/test/cerr_logger_test.cc    | 209 ++++++++++++++++++++++++++++++++
 src/iceberg/test/meson.build            |   8 +-
 src/iceberg/util/thread_util.cc         |  49 ++++++++
 src/iceberg/util/thread_util_internal.h |  36 ++++++
 13 files changed, 463 insertions(+), 15 deletions(-)

diff --git a/ci/scripts/build_example.sh b/ci/scripts/build_example.sh
index 77abbc31..41714cf3 100755
--- a/ci/scripts/build_example.sh
+++ b/ci/scripts/build_example.sh
@@ -23,7 +23,8 @@ source_dir=${1}
 build_dir=${1}/build
 run_example=${ICEBERG_RUN_EXAMPLE:-OFF}
 
-mkdir ${build_dir}
+rm -rf "${build_dir}"
+mkdir "${build_dir}"
 pushd ${build_dir}
 
 is_windows() {
@@ -60,6 +61,3 @@ else
 fi
 
 popd
-
-# clean up between builds
-rm -rf ${build_dir}
diff --git a/src/iceberg/CMakeLists.txt b/src/iceberg/CMakeLists.txt
index aa051cd1..94523fb5 100644
--- a/src/iceberg/CMakeLists.txt
+++ b/src/iceberg/CMakeLists.txt
@@ -49,6 +49,7 @@ 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
@@ -133,6 +134,7 @@ set(ICEBERG_SOURCES
     util/struct_like_set.cc
     util/task_group.cc
     util/temporal_util.cc
+    util/thread_util.cc
     util/timepoint.cc
     util/transform_util.cc
     util/truncate_util.cc
diff --git a/src/iceberg/logging/cerr_logger.cc b/src/iceberg/logging/cerr_logger.cc
new file mode 100644
index 00000000..0856d963
--- /dev/null
+++ b/src/iceberg/logging/cerr_logger.cc
@@ -0,0 +1,77 @@
+/*
+ * 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 <format>
+#include <iostream>
+#include <mutex>
+#include <string>
+#include <string_view>
+
+#include "iceberg/util/thread_util_internal.h"
+
+namespace iceberg {
+
+namespace {
+
+/// \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. Reached if either formatting or the write fails;
+    // emit a short marker best-effort and swallow anything further.
+    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
diff --git a/src/iceberg/logging/cerr_logger.h b/src/iceberg/logging/cerr_logger.h
new file mode 100644
index 00000000..334f2039
--- /dev/null
+++ b/src/iceberg/logging/cerr_logger.h
@@ -0,0 +1,61 @@
+/*
+ * 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 noexcept override {
+    return level >= level_.load(std::memory_order_relaxed);
+  }
+  void Log(LogMessage&& message) noexcept override;
+  void SetLevel(LogLevel level) noexcept override {
+    level_.store(level, std::memory_order_relaxed);
+  }
+  LogLevel level() const noexcept override {
+    return level_.load(std::memory_order_relaxed);
+  }
+  void Flush() noexcept override;
+
+ private:
+  std::atomic<LogLevel> level_;
+  std::mutex mutex_;
+};
+
+}  // namespace iceberg
diff --git a/src/iceberg/logging/logger.cc b/src/iceberg/logging/logger.cc
index 3adbf75d..a8db67ca 100644
--- a/src/iceberg/logging/logger.cc
+++ b/src/iceberg/logging/logger.cc
@@ -26,6 +26,8 @@
 #include <tuple>
 #include <utility>
 
+#include "iceberg/logging/cerr_logger.h"
+
 namespace iceberg {
 
 namespace {
@@ -42,10 +44,9 @@ class NoopLogger final : public Logger {
 
 /// \brief Construct the process default logger for this build configuration.
 ///
-/// This block ships only the interface and the no-op logger; the concrete
-/// std::cerr and spdlog sinks (and the build-config selection between them)
-/// arrive in later blocks, which update this factory.
-std::shared_ptr<Logger> MakeDefaultLogger() { return std::make_shared<NoopLogger>(); }
+/// Uses the always-available std::cerr sink. The spdlog backend (preferred when
+/// compiled in) is wired into this factory in a later block.
+std::shared_ptr<Logger> MakeDefaultLogger() { return std::make_shared<CerrLogger>(); }
 
 /// \brief The process-global default-logger slot.
 struct DefaultSlot {
diff --git a/src/iceberg/logging/logger.h b/src/iceberg/logging/logger.h
index 8a642f83..66f81501 100644
--- a/src/iceberg/logging/logger.h
+++ b/src/iceberg/logging/logger.h
@@ -127,8 +127,8 @@ class ICEBERG_EXPORT LogMessage::Builder {
 /// \brief Well-known Logger::Initialize() property keys.
 ///
 /// `level` is honored by the base Logger::Initialize (parsed via
-/// LogLevelFromString). `pattern` is honored by the formatting sinks
-/// (CerrLogger, SpdLogger).
+/// LogLevelFromString) on every backend. `pattern` is honored only by the
+/// spdlog backend; CerrLogger uses a fixed layout and ignores it.
 inline constexpr std::string_view kLevelProperty = "level";
 inline constexpr std::string_view kPatternProperty = "pattern";
 
@@ -150,8 +150,8 @@ class ICEBERG_EXPORT Logger {
   ///
   /// The base implementation applies the "level" property (parsed via
   /// LogLevelFromString); an unrecognized value is an InvalidArgument error.
-  /// Formatting sinks override this to also apply "pattern" and then delegate
-  /// to this base for "level".
+  /// The spdlog backend overrides this to also apply "pattern" and then delegates
+  /// to this base for "level"; CerrLogger uses the base as-is (fixed layout).
   virtual Status Initialize(
       const std::unordered_map<std::string, std::string>& properties) {
     if (auto it = properties.find(std::string(kLevelProperty)); it != properties.end()) {
diff --git a/src/iceberg/logging/meson.build b/src/iceberg/logging/meson.build
index 3f7af4fe..e4ca111f 100644
--- a/src/iceberg/logging/meson.build
+++ b/src/iceberg/logging/meson.build
@@ -15,4 +15,7 @@
 # specific language governing permissions and limitations
 # under the License.
 
-install_headers(['log_level.h', 'logger.h'], subdir: 'iceberg/logging')
+install_headers(
+    ['cerr_logger.h', 'log_level.h', 'logger.h'],
+    subdir: 'iceberg/logging',
+)
diff --git a/src/iceberg/meson.build b/src/iceberg/meson.build
index 58d79a40..71a4498f 100644
--- a/src/iceberg/meson.build
+++ b/src/iceberg/meson.build
@@ -74,6 +74,7 @@ iceberg_sources = files(
     'inspect/snapshots_table.cc',
     'json_serde.cc',
     'location_provider.cc',
+    'logging/cerr_logger.cc',
     'logging/logger.cc',
     'manifest/manifest_adapter.cc',
     'manifest/manifest_entry.cc',
@@ -158,6 +159,7 @@ iceberg_sources = files(
     'util/struct_like_set.cc',
     'util/task_group.cc',
     'util/temporal_util.cc',
+    'util/thread_util.cc',
     'util/timepoint.cc',
     'util/transform_util.cc',
     'util/truncate_util.cc',
diff --git a/src/iceberg/test/CMakeLists.txt b/src/iceberg/test/CMakeLists.txt
index 0756c1ee..fcbc2212 100644
--- a/src/iceberg/test/CMakeLists.txt
+++ b/src/iceberg/test/CMakeLists.txt
@@ -102,7 +102,11 @@ add_iceberg_test(table_test
                  table_test.cc
                  table_update_test.cc)
 
-add_iceberg_test(logging_test SOURCES log_level_test.cc logger_test.cc)
+add_iceberg_test(logging_test
+                 SOURCES
+                 cerr_logger_test.cc
+                 log_level_test.cc
+                 logger_test.cc)
 
 add_iceberg_test(expression_test
                  SOURCES
diff --git a/src/iceberg/test/cerr_logger_test.cc b/src/iceberg/test/cerr_logger_test.cc
new file mode 100644
index 00000000..9a44dfca
--- /dev/null
+++ b/src/iceberg/test/cerr_logger_test.cc
@@ -0,0 +1,209 @@
+/*
+ * 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 <cstddef>
+#include <format>
+#include <iostream>
+#include <regex>
+#include <set>
+#include <source_location>
+#include <sstream>
+#include <streambuf>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include <gtest/gtest.h>
+
+#include "iceberg/logging/log_level.h"
+#include "iceberg/logging/logger.h"
+
+namespace iceberg {
+
+namespace {
+
+/// \brief RAII redirect of std::cerr to a stringstream for the test scope.
+class CerrCapture {
+ public:
+  CerrCapture() : old_(std::cerr.rdbuf(buffer_.rdbuf())) {}
+  ~CerrCapture() { std::cerr.rdbuf(old_); }
+  std::string str() const { return buffer_.str(); }
+
+ private:
+  std::ostringstream buffer_;
+  std::streambuf* old_;
+};
+
+LogMessage MakeMessage(LogLevel level, std::string text) {
+  return LogMessage{.level = level,
+                    .message = std::move(text),
+                    .location = std::source_location::current(),
+                    .attributes = {}};
+}
+
+/// \brief First line of \p text, without the trailing newline.
+std::string FirstLine(const std::string& text) {
+  auto pos = text.find('\n');
+  return text.substr(0, pos == std::string::npos ? text.size() : pos);
+}
+
+/// \brief A streambuf that throws on every write, to drive the never-throw path.
+///
+/// Throws a payload-less exception on purpose: an exception type with a
+/// heap-allocated what() string (e.g. std::runtime_error) trips an ASan
+/// alloc-dealloc-mismatch as the string crosses the instrumented binary /
+/// system libc++abi boundary during unwinding -- unrelated to the code here.
+struct SinkFailure {};
+class ThrowingBuf : public std::streambuf {
+ protected:
+  int overflow(int /*ch*/) override { throw SinkFailure{}; }
+  std::streamsize xsputn(const char* /*s*/, std::streamsize /*n*/) override {
+    throw SinkFailure{};
+  }
+};
+
+/// \brief RAII: point std::cerr at a throwing buffer with exceptions armed, and
+/// restore all of cerr's state (buffer, exception mask, error flags) on exit --
+/// so a thrown assertion can never leak the dangling/throwing stream to other
+/// tests.
+class CerrThrowingGuard {
+ public:
+  CerrThrowingGuard()
+      : old_buf_(std::cerr.rdbuf(&buf_)), old_exc_(std::cerr.exceptions()) {
+    std::cerr.exceptions(std::ios::badbit | std::ios::failbit);  // make << rethrow
+  }
+  ~CerrThrowingGuard() {
+    std::cerr.clear();
+    std::cerr.exceptions(old_exc_);
+    std::cerr.rdbuf(old_buf_);
+  }
+
+ private:
+  ThrowingBuf buf_;
+  std::streambuf* old_buf_;
+  std::ios_base::iostate old_exc_;
+};
+
+}  // namespace
+
+TEST(CerrLoggerTest, DefaultLevelIsInfo) {
+  CerrLogger logger;
+  EXPECT_EQ(logger.level(), LogLevel::kInfo);
+  EXPECT_FALSE(logger.ShouldLog(LogLevel::kDebug));
+  EXPECT_TRUE(logger.ShouldLog(LogLevel::kInfo));
+  EXPECT_TRUE(logger.ShouldLog(LogLevel::kError));
+}
+
+TEST(CerrLoggerTest, SetLevelFilters) {
+  CerrLogger logger(LogLevel::kError);
+  EXPECT_FALSE(logger.ShouldLog(LogLevel::kWarn));
+  logger.SetLevel(LogLevel::kTrace);
+  EXPECT_TRUE(logger.ShouldLog(LogLevel::kTrace));
+}
+
+TEST(CerrLoggerTest, LineContainsLevelAndMessage) {
+  CerrLogger logger;
+  CerrCapture capture;
+  logger.Log(MakeMessage(LogLevel::kError, "boom 42"));
+  std::string out = capture.str();
+  EXPECT_NE(out.find("error"), std::string::npos);
+  EXPECT_NE(out.find("boom 42"), std::string::npos);
+  EXPECT_NE(out.find("cerr_logger_test.cc"), std::string::npos);
+  EXPECT_EQ(out.back(), '\n');
+}
+
+// The whole value of CerrLogger over a backend is its fixed line layout:
+// `YYYY-MM-DDThh:mm:ss.mmmZ LEVEL [tid] [file:line] message`. Assert the shape,
+// especially the .mmm millisecond field (which silently vanishes if the
+// time_point is no longer floored to milliseconds).
+TEST(CerrLoggerTest, LineMatchesFixedLayout) {
+  CerrLogger logger;
+  CerrCapture capture;
+  logger.Log(MakeMessage(LogLevel::kWarn, "hello world"));
+  const std::regex layout(
+      R"(^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z \w+ \[\d+\] \[\S+:\d+\] hello world$)");
+  EXPECT_TRUE(std::regex_match(FirstLine(capture.str()), layout)) << capture.str();
+}
+
+// CerrLogger deliberately does not override Initialize: it inherits the base,
+// which applies "level" and ignores unknown keys like "pattern".
+TEST(CerrLoggerTest, InitializeAppliesLevelAndIgnoresPattern) {
+  CerrLogger logger;
+  auto status = logger.Initialize({{std::string(kLevelProperty), "warn"},
+                                   {std::string(kPatternProperty), "ignored"}});
+  ASSERT_TRUE(status.has_value());
+  EXPECT_EQ(logger.level(), LogLevel::kWarn);
+}
+
+TEST(CerrLoggerTest, FlushDoesNotThrow) {
+  CerrLogger logger;
+  CerrCapture capture;
+  logger.Log(MakeMessage(LogLevel::kError, "x"));
+  logger.Flush();  // best-effort; must not throw
+  EXPECT_NE(capture.str().find('x'), std::string::npos);
+}
+
+// Log()/Flush() are noexcept: even when every write to the sink throws, they
+// must swallow it (a leaked exception from a noexcept function -> std::terminate).
+TEST(CerrLoggerTest, LogAndFlushNeverThrowWhenSinkThrows) {
+  CerrThrowingGuard guard;  // cerr -> throwing sink; state restored on scope exit
+  CerrLogger logger(LogLevel::kTrace);
+  logger.Log(MakeMessage(LogLevel::kInfo, "x"));  // write throws -> fallback also throws
+  logger.Flush();
+  SUCCEED();
+}
+
+TEST(CerrLoggerTest, ConcurrentLogsDoNotInterleave) {
+  CerrLogger logger(LogLevel::kTrace);
+  CerrCapture capture;
+  constexpr int kThreads = 8;
+  constexpr int kPerThread = 50;
+
+  std::vector<std::thread> threads;
+  for (int t = 0; t < kThreads; ++t) {
+    threads.emplace_back([&logger, t] {
+      for (int i = 0; i < kPerThread; ++i) {
+        // Distinct payload per record so an interleave would corrupt a line.
+        logger.Log(MakeMessage(LogLevel::kInfo, std::format("t{}-{}", t, i)));
+      }
+    });
+  }
+  for (auto& thread : threads) thread.join();
+
+  // Each output line must be a complete, well-formed record ending in its own
+  // payload, and every (thread, index) payload must appear exactly once -- this
+  // proves the whole-line write is atomic, not merely that newlines were kept.
+  const std::regex line(R"(^.*\] (t\d+-\d+)$)");
+  std::set<std::string> seen;
+  std::istringstream in(capture.str());
+  std::string row;
+  int lines = 0;
+  while (std::getline(in, row)) {
+    ++lines;
+    std::smatch m;
+    ASSERT_TRUE(std::regex_match(row, m, line)) << "garbled line: " << row;
+    EXPECT_TRUE(seen.insert(m[1].str()).second) << "duplicate payload: " << m[1].str();
+  }
+  EXPECT_EQ(lines, kThreads * kPerThread);
+  EXPECT_EQ(seen.size(), static_cast<std::size_t>(kThreads * kPerThread));
+}
+
+}  // namespace iceberg
diff --git a/src/iceberg/test/meson.build b/src/iceberg/test/meson.build
index b01a6190..ba0f6230 100644
--- a/src/iceberg/test/meson.build
+++ b/src/iceberg/test/meson.build
@@ -61,7 +61,13 @@ iceberg_tests = {
             'table_update_test.cc',
         ),
     },
-    'logging_test': {'sources': files('log_level_test.cc', 'logger_test.cc')},
+    'logging_test': {
+        'sources': files(
+            'cerr_logger_test.cc',
+            'log_level_test.cc',
+            'logger_test.cc',
+        ),
+    },
     'expression_test': {
         'sources': files(
             'aggregate_test.cc',
diff --git a/src/iceberg/util/thread_util.cc b/src/iceberg/util/thread_util.cc
new file mode 100644
index 00000000..ed6cccfa
--- /dev/null
+++ b/src/iceberg/util/thread_util.cc
@@ -0,0 +1,49 @@
+/*
+ * 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/util/thread_util_internal.h"
+
+#if defined(_WIN32)
+#  include <windows.h>
+#elif defined(__APPLE__)
+#  include <pthread.h>
+#else
+#  include <unistd.h>
+
+#  include <sys/syscall.h>
+#endif
+
+namespace iceberg {
+
+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;
+}
+
+}  // namespace iceberg
diff --git a/src/iceberg/util/thread_util_internal.h b/src/iceberg/util/thread_util_internal.h
new file mode 100644
index 00000000..ebd18fca
--- /dev/null
+++ b/src/iceberg/util/thread_util_internal.h
@@ -0,0 +1,36 @@
+/*
+ * 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
+
+#include <cstdint>
+
+namespace iceberg {
+
+/// \brief OS-native thread id for the calling thread, cached per thread.
+///
+/// Returns the cross-process-correlatable id used by spdlog/glog (Linux
+/// gettid, macOS pthread_threadid_np, Windows GetCurrentThreadId), not the
+/// opaque std::thread::id -- and so avoids the std::formatter<std::thread::id>
+/// (P2693) minimum-toolchain dependency. The first call on a thread performs
+/// the OS query; later calls return the cached value (no syscall per call).
+/// Declared here so the platform headers stay confined to the .cc.
+uint64_t OsThreadId() noexcept;
+
+}  // namespace iceberg