Add log levels for the new logging system

This is the first of six small PRs that together add a logging system to
iceberg-cpp. It introduces LogLevel, the severity scale everything else builds
on: trace, debug, info, warn, error, critical, fatal, plus an `off` sentinel for
turning logging off entirely.

Levels are ordered from most to least verbose, so deciding whether something
should be logged is a plain `level >= threshold` comparison. Two helpers come
with it: ToString to print a level, and LogLevelFromString to parse one
(case-insensitive, returning a Result for unrecognized input). Both follow the
same shape as CounterUnit in metrics/counter.h.

There is no implementation behind the header yet, so this PR only adds the
header, wires the new src/iceberg/logging directory into the build, and adds a
test covering the round-trip, ordering, and parsing.

Co-authored-by: Isaac

Author: kamcheungting-db

src/iceberg/CMakeLists.txt

@@ -239,6 +239,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/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/test/CMakeLists.txt

@@ -101,6 +101,8 @@ 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(expression_test
                  SOURCES
                  aggregate_test.cc

src/iceberg/test/log_level_test.cc

@@ -0,0 +1,78 @@
+/*
+ * 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/log_level.h"
+
+#include <array>
+#include <string>
+
+#include <gtest/gtest.h>
+
+namespace iceberg {
+
+namespace {
+
+constexpr std::array<LogLevel, 8> kAllLevels = {
+    LogLevel::kTrace, LogLevel::kDebug,    LogLevel::kInfo,  LogLevel::kWarn,
+    LogLevel::kError, LogLevel::kCritical, LogLevel::kFatal, LogLevel::kOff};
+
+}  // namespace
+
+TEST(LogLevelTest, ToStringCoversEveryLevel) {
+  EXPECT_EQ(ToString(LogLevel::kTrace), "trace");
+  EXPECT_EQ(ToString(LogLevel::kDebug), "debug");
+  EXPECT_EQ(ToString(LogLevel::kInfo), "info");
+  EXPECT_EQ(ToString(LogLevel::kWarn), "warn");
+  EXPECT_EQ(ToString(LogLevel::kError), "error");
+  EXPECT_EQ(ToString(LogLevel::kCritical), "critical");
+  EXPECT_EQ(ToString(LogLevel::kFatal), "fatal");
+  EXPECT_EQ(ToString(LogLevel::kOff), "off");
+}
+
+TEST(LogLevelTest, FromStringRoundTrips) {
+  for (LogLevel level : kAllLevels) {
+    auto parsed = LogLevelFromString(ToString(level));
+    ASSERT_TRUE(parsed.has_value()) << "failed to parse " << ToString(level);
+    EXPECT_EQ(parsed.value(), level);
+  }
+}
+
+TEST(LogLevelTest, FromStringIsCaseInsensitive) {
+  EXPECT_EQ(LogLevelFromString("WARN").value(), LogLevel::kWarn);
+  EXPECT_EQ(LogLevelFromString("Warn").value(), LogLevel::kWarn);
+  EXPECT_EQ(LogLevelFromString("CRITICAL").value(), LogLevel::kCritical);
+}
+
+TEST(LogLevelTest, FromStringRejectsUnknown) {
+  auto parsed = LogLevelFromString("verbose");
+  ASSERT_FALSE(parsed.has_value());
+  EXPECT_EQ(parsed.error().kind, ErrorKind::kInvalidArgument);
+}
+
+TEST(LogLevelTest, OrderingIsMonotonicWithOffAsMaximum) {
+  EXPECT_LT(LogLevel::kTrace, LogLevel::kDebug);
+  EXPECT_LT(LogLevel::kDebug, LogLevel::kInfo);
+  EXPECT_LT(LogLevel::kInfo, LogLevel::kWarn);
+  EXPECT_LT(LogLevel::kWarn, LogLevel::kError);
+  EXPECT_LT(LogLevel::kError, LogLevel::kCritical);
+  EXPECT_LT(LogLevel::kCritical, LogLevel::kFatal);
+  EXPECT_LT(LogLevel::kFatal, LogLevel::kOff);
+}
+
+}  // namespace iceberg