feat(logging): add Logger interface and default logger (2/6)

[kamcheungting-db]

Part 2 of the logging stack (builds on #722). Adds the logging API and a swappable default logger — the foundation the backends and macros plug into.

What's here

• Logger: the pluggable sink interface (ShouldLog / Log / SetLevel / Flush / Initialize). ShouldLog() is the single source of truth for runtime filtering.
• LogMessage owns its formatted text so a sink can safely keep a record; reserves an attributes field for future structured logging.
• Process-global default logger: GetDefaultLogger / SetDefaultLogger / SetDefaultLevel, with a lock-free thread-local fast path so logging stays cheap.
• Initialize applies the level property, so config-driven levels actually work. CurrentLogger() is safe to call even from a thread_local destructor during thread shutdown.
• logger.h stays backend-agnostic (never includes the build config header), so consumers see one stable API regardless of backend.

Examples — using the API directly (the LOG_* macros that wrap it arrive in #725):

// A custom sink, installed as the process default.
class MySink : public Logger {
 public:
  bool ShouldLog(LogLevel level) const override { return level >= level_; }
  void Log(LogMessage&& m) noexcept override { write_line(m.message); }
  void SetLevel(LogLevel level) override { level_ = level; }
  LogLevel level() const override { return level_; }
 private:
  std::atomic<LogLevel> level_{LogLevel::kInfo};
};

SetDefaultLogger(std::make_shared<MySink>());   // install process-wide
SetDefaultLevel(LogLevel::kDebug);              // adjust the threshold

auto logger = GetDefaultLogger();               // borrow the current default
if (logger->ShouldLog(LogLevel::kInfo)) {
  logger->Log(LogMessage{.level = LogLevel::kInfo, .message = "scan ready"});
}

// Or configure from catalog-style properties (applies the "level" key):
auto sink = std::make_shared<MySink>();
auto status = sink->Initialize({{std::string(kLevelProperty), "warn"}});  // -> kWarn

The same example is documented inline in logger.h.

Tests — logger_test: default-logger API, level-from-property, invalid level rejected, concurrent swap/read, and logging during thread teardown. Built and run with clang/libc++ (spdlog ON and OFF).

This pull request and its description were written by Isaac.

[wgtmac]

Suggested change

	(void)l->ShouldLog(LogLevel::kError);
	(void)GetDefaultLogger();
	std::ignore = l->ShouldLog(LogLevel::kError);
	std::ignore = GetDefaultLogger();

[kamcheungting-db]

Done

[wgtmac]

Let's use IsError matcher.

[kamcheungting-db]

Done

[wgtmac]

Do we need to add ICEBERG_EXPORT to this and below?

[kamcheungting-db]

Done

[wgtmac]

The doc says logger implementations must not throw. ShouldLog() is also in the hot path.

But the virtual method is not noexcept. A custom engine logger may throw here by mistake. Then logging can throw from the filter path. Adding noexcept later is also an API/ABI change.

Can we mark ShouldLog() noexcept now? Maybe SetLevel() and level() too, if we want the same rule for all logger methods.

[kamcheungting-db]

done

[wgtmac]

Small doc issue. This header says it has logging macros, but this PR does not add them.

The PR text says macros are in a later block. Users who read the installed header may be confused.

Maybe say this header has the logger API and macro helper hooks. Or move this sentence to the later PR.

[kamcheungting-db]

done.

[wgtmac]

The comment says this API never throws, but the public Log overload itself is not marked noexcept. The helper is noexcept, so the contract is only missing at the public boundary.

Can we mark both public Log overloads noexcept to make the no-throw contract explicit?

[kamcheungting-db]

Done.
Now, both public Log() overloads are now noexcept.

[wgtmac]

This default location is not the user call site. Since location_ is initialized in the header, Builder(...).Build() records logger.h instead of the caller file/line.

Can we take std::source_location in the Builder constructor, with current() as the default argument, and add a test that checks the recorded line is the call site?

[kamcheungting-db]

Done

[wgtmac]

I think this still gives the wrong default location. Now the test makes the default point to logger.h / Builder, but users will expect the record to point to their call site.

Can we make the constructor take std::source_location with current() as a default argument, and test that the default location is the Builder call site?

Example:

explicit Builder(LogLevel level,
std::source_location location = std::source_location::current())
: level_(level), location_(location) {}

[kamcheungting-db]

You are right.

explicit Builder(LogLevel level,
                  std::source_location location = std::source_location::current())
     : level_(level), location_(location) {}

TEST(LoggerTest, BuilderDefaultLocationIsCallerSite) {
  auto here = std::source_location::current();
  auto record = LogMessage::Builder(LogLevel::kInfo).Message("m").Build();
  EXPECT_STREQ(record.location.file_name(), here.file_name());
  EXPECT_EQ(record.location.line(), here.line() + 1);
}

[kamcheungting-db]

Done

[wgtmac]

LGTM, thanks @kamcheungting-db!