[k2] implement user-defined tags in logs (#1386)

implement function `kphp_set_context_on_error`
implement raw and contextual loggers in runtime-light

Author: astrophysik

builtin-functions/kphp-light/stdlib/error.txt

@@ -2,7 +2,7 @@
 
 // === SUPPORTED ===
 
-function kphp_set_context_on_error(mixed[] $tags, mixed $extra_info, string $env = "") ::: void;
+function kphp_set_context_on_error(mixed[] $tags, ?mixed[] $extra_info = null, ?string $env = null) ::: void;
 
 interface Throwable {
     public function getMessage () ::: string;

runtime-light/state/instance-state.h

@@ -21,6 +21,7 @@
 #include "runtime-light/server/job-worker/job-worker-server-state.h"
 #include "runtime-light/server/rpc/rpc-server-state.h"
 #include "runtime-light/stdlib/curl/curl-state.h"
+#include "runtime-light/stdlib/diagnostics/contextual-logger.h"
 #include "runtime-light/stdlib/fork/fork-state.h"
 #include "runtime-light/stdlib/instance-cache/instance-cache-state.h"
 #include "runtime-light/stdlib/job-worker/job-worker-client-state.h"
@@ -79,6 +80,7 @@ struct InstanceState final : vk::not_copyable {
   }
 
   AllocatorState instance_allocator_state{INIT_INSTANCE_ALLOCATOR_SIZE, 0};
+  kphp::log::contextual_logger instance_logger;
 
   kphp::coro::io_scheduler io_scheduler;
   CoroutineInstanceState coroutine_instance_state;

runtime-light/stdlib/diagnostics/contextual-logger.cpp

@@ -0,0 +1,51 @@
+// Compiler for PHP (aka KPHP)
+// Copyright (c) 2025 LLC «V Kontakte»
+// Distributed under the GPL v3 License, see LICENSE.notice.txt
+
+#include "runtime-light/stdlib/diagnostics/contextual-logger.h"
+
+#include <cstddef>
+#include <functional>
+#include <optional>
+#include <span>
+#include <string_view>
+#include <utility>
+
+#include "runtime-common/core/allocator/script-allocator.h"
+#include "runtime-common/core/std/containers.h"
+#include "runtime-light/k2-platform/k2-api.h"
+#include "runtime-light/state/instance-state.h"
+#include "runtime-light/stdlib/diagnostics/detail/logs.h"
+
+namespace kphp::log {
+
+std::optional<std::reference_wrapper<contextual_logger>> contextual_logger::try_get() noexcept {
+  if (auto* instance_state_ptr{k2::instance_state()}; instance_state_ptr != nullptr) [[likely]] {
+    return instance_state_ptr->instance_logger;
+  }
+  return std::nullopt;
+}
+
+void contextual_logger::log_with_tags(kphp::log::level level, std::optional<std::span<void* const>> trace, std::string_view message) const noexcept {
+  kphp::stl::vector<k2::LogTaggedEntry, kphp::memory::script_allocator> tagged_entries{};
+  const bool is_extra_tags_enabled{level == level::warn || level == level::error};
+  const size_t tagged_entries_size{static_cast<size_t>((trace.has_value() ? 1 : 0) + (is_extra_tags_enabled ? extra_tags.size() : 0))};
+  tagged_entries.reserve(tagged_entries_size);
+  if (is_extra_tags_enabled) {
+    for (const auto& [key, value] : extra_tags) {
+      tagged_entries.push_back(k2::LogTaggedEntry{.key = key.data(), .value = value.data(), .key_len = key.size(), .value_len = value.size()});
+    }
+  }
+  if (trace.has_value()) {
+    static constexpr size_t BACKTRACE_BUFFER_SIZE = 1024UZ * 4UZ;
+    std::array<char, BACKTRACE_BUFFER_SIZE> backtrace_buffer; // NOLINT
+    size_t backtrace_size{impl::resolve_log_trace(backtrace_buffer, *trace)};
+    tagged_entries.push_back(
+        k2::LogTaggedEntry{.key = BACKTRACE_KEY.data(), .value = backtrace_buffer.data(), .key_len = BACKTRACE_KEY.size(), .value_len = backtrace_size});
+    k2::log(std::to_underlying(level), message, tagged_entries);
+    return;
+  }
+  k2::log(std::to_underlying(level), message, tagged_entries);
+}
+
+} // namespace kphp::log

runtime-light/stdlib/diagnostics/contextual-logger.h

@@ -0,0 +1,104 @@
+// Compiler for PHP (aka KPHP)
+// Copyright (c) 2025 LLC «V Kontakte»
+// Distributed under the GPL v3 License, see LICENSE.notice.txt
+
+#pragma once
+
+#include <cstddef>
+#include <format>
+#include <functional>
+#include <optional>
+#include <span>
+#include <string_view>
+#include <utility>
+
+#include "common/mixin/not_copyable.h"
+#include "runtime-common/core/allocator/script-allocator.h"
+#include "runtime-common/core/std/containers.h"
+#include "runtime-light/stdlib/diagnostics/detail/logs.h"
+
+namespace kphp::log {
+
+class contextual_logger final : vk::not_copyable {
+  using tag_key_t = kphp::stl::string<kphp::memory::script_allocator>;
+  using tag_value_t = kphp::stl::string<kphp::memory::script_allocator>;
+
+  struct extra_tags_hash final {
+    using is_transparent = void;
+
+    size_t operator()(std::string_view sv) const noexcept {
+      return std::hash<std::string_view>{}(sv);
+    }
+
+    size_t operator()(const tag_key_t& s) const noexcept {
+      return std::hash<tag_key_t>{}(s);
+    }
+  };
+
+  struct extra_tags_equal final {
+    using is_transparent = void;
+
+    constexpr bool operator()(std::string_view lhs, std::string_view rhs) const noexcept {
+      return lhs == rhs;
+    }
+
+    constexpr bool operator()(const tag_key_t& lhs, const tag_key_t& rhs) const noexcept {
+      return lhs == rhs;
+    }
+
+    constexpr bool operator()(std::string_view lhs, const tag_key_t& rhs) const noexcept {
+      return lhs == rhs;
+    }
+
+    constexpr bool operator()(const tag_key_t& lhs, std::string_view rhs) const noexcept {
+      return lhs == rhs;
+    }
+  };
+
+  static constexpr std::string_view BACKTRACE_KEY = "trace";
+
+  kphp::stl::unordered_map<tag_key_t, tag_value_t, kphp::memory::script_allocator, extra_tags_hash, extra_tags_equal> extra_tags;
+
+  void log_with_tags(kphp::log::level level, std::optional<std::span<void* const>> trace, std::string_view message) const noexcept;
+
+public:
+  template<typename... Args>
+  void log(kphp::log::level level, std::optional<std::span<void* const>> trace, std::format_string<impl::wrapped_arg_t<Args>...> fmt,
+           Args&&... args) const noexcept;
+
+  void add_extra_tag(std::string_view key, std::string_view value) noexcept;
+  void remove_extra_tag(std::string_view key) noexcept;
+  void clear_extra_tags() noexcept;
+
+  static std::optional<std::reference_wrapper<contextual_logger>> try_get() noexcept;
+};
+
+template<typename... Args>
+void contextual_logger::log(kphp::log::level level, std::optional<std::span<void* const>> trace, std::format_string<impl::wrapped_arg_t<Args>...> fmt,
+                            Args&&... args) const noexcept {
+  static constexpr size_t LOG_BUFFER_SIZE = 512UZ;
+  std::array<char, LOG_BUFFER_SIZE> log_buffer; // NOLINT
+  size_t message_size{impl::format_log_message(log_buffer, fmt, std::forward<Args>(args)...)};
+  auto message{std::string_view{log_buffer.data(), static_cast<std::string_view::size_type>(message_size)}};
+  log_with_tags(level, trace, message);
+}
+
+inline void contextual_logger::add_extra_tag(std::string_view key, std::string_view value) noexcept {
+  if (auto it{extra_tags.find(key)}; it == extra_tags.end()) {
+    extra_tags.emplace(key, value);
+  } else {
+    it->second = value;
+  }
+}
+
+inline void contextual_logger::remove_extra_tag(std::string_view key) noexcept {
+  if (auto it{extra_tags.find(key)}; it != extra_tags.end()) {
+    extra_tags.erase(it);
+  }
+}
+
+inline void contextual_logger::clear_extra_tags() noexcept {
+  extra_tags.clear();
+}
+
+} // namespace kphp::log

runtime-light/stdlib/diagnostics/detail/logs.h

@@ -0,0 +1,70 @@
+// Compiler for PHP (aka KPHP)
+// Copyright (c) 2025 LLC «V Kontakte»
+// Distributed under the GPL v3 License, see LICENSE.notice.txt
+
+#pragma once
+
+#include <cstddef>
+#include <cstring>
+#include <format>
+#include <span>
+#include <string_view>
+#include <type_traits>
+
+#include "runtime-light/stdlib/diagnostics/backtrace.h"
+
+namespace kphp::log {
+
+namespace impl {
+template<typename T>
+requires std::is_floating_point_v<std::remove_cvref_t<T>>
+struct floating_wrapper final {
+  T value{};
+};
+
+template<typename T>
+constexpr auto wrap_log_argument(T&& t) noexcept -> decltype(auto) {
+  if constexpr (std::is_floating_point_v<std::remove_cvref_t<T>>) {
+    return impl::floating_wrapper<std::remove_cvref_t<T>>{.value = std::forward<T>(t)};
+  } else {
+    return std::forward<T>(t);
+  }
+}
+
+template<typename T>
+using wrapped_arg_t = std::invoke_result_t<decltype(impl::wrap_log_argument<T>), T>;
+
+template<typename... Args>
+size_t format_log_message(std::span<char> message_buffer, std::format_string<impl::wrapped_arg_t<Args>...> fmt, Args&&... args) noexcept {
+  auto [out, size]{std::format_to_n<decltype(message_buffer.data()), impl::wrapped_arg_t<Args>...>(message_buffer.data(), message_buffer.size() - 1, fmt,
+                                                                                                   impl::wrap_log_argument(std::forward<Args>(args))...)};
+  *out = '\0';
+  return size;
+}
+
+inline size_t resolve_log_trace(std::span<char> trace_buffer, std::span<void* const> raw_trace) noexcept {
+  if (trace_buffer.empty()) {
+    return 0;
+  }
+
+  if (auto backtrace_symbols{kphp::diagnostic::backtrace_symbols(raw_trace)}; !backtrace_symbols.empty()) {
+    const auto [trace_out, trace_size]{std::format_to_n(trace_buffer.data(), trace_buffer.size() - 1, "\n{}", backtrace_symbols)};
+    *trace_out = '\0';
+    return trace_size;
+  } else if (auto backtrace_addresses{kphp::diagnostic::backtrace_addresses(raw_trace)}; !backtrace_addresses.empty()) {
+    const auto [trace_out, trace_size]{std::format_to_n(trace_buffer.data(), trace_buffer.size() - 1, "{}", backtrace_addresses)};
+    *trace_out = '\0';
+    return trace_size;
+  } else {
+    static constexpr std::string_view DEFAULT_TRACE = "[]";
+    const auto [trace_out, trace_size]{std::format_to_n(trace_buffer.data(), trace_buffer.size() - 1, "{}", DEFAULT_TRACE)};
+    *trace_out = '\0';
+    return trace_size;
+  }
+}
+
+} // namespace impl
+
+enum class level : size_t { error = 1, warn, info, debug, trace }; // NOLINT
+
+} // namespace kphp::log