diagnostics.hpp

Go to the documentation of this file.

#pragma once
 
// ============================================================================
//  aria/diagnostics.hpp
// ----------------------------------------------------------------------------
//  Unified diagnostic protocol for the Aria framework. Per
//  docs/diagnostics.md, every observable subsystem publishes
//  `TraceEvent`s through a single, optional, thread-safe sink:
//
//    - reactive graph flush  -> Category::Reactive
//    - async command         -> Category::Async
//    - async resource        -> Category::Async
//    - binding engine        -> Category::Binding
//    - command (sync)        -> Category::Command
//    - validator             -> Category::Validation
//    - observable list       -> Category::List
//
//  Design pillars
//  --------------
//   1. A cheap disabled path: the has_trace_sink gate costs
//      one atomic load + one branch. No string is built, no allocation
//      is done.
//
//   2. Single value type (`TraceEvent`) so tooling consumes ONE shape;
//      heterogeneous payloads are boxed into a small `std::variant`.
//
//   3. Thread-safe sink registration: a sink may be installed /
//      replaced / cleared from any thread at any time. Concurrent
//      publishers see a consistent snapshot via `std::shared_ptr`.
//
//   4. Aria's own subsystems are ALLOWED to keep their own focused
//      tracers (e.g. `GraphInspector::install_flush_tracer`); the
//      unified sink is an additional fanout, NOT a replacement.
//
//  Per docs/api-style.md S-1 these names live in `aria::`.
// ============================================================================
 
#include "aria/abi/export.hpp"
#include "aria/error.hpp"
#include "aria/validation_key.hpp"
 
#include <atomic>
#include <chrono>
#include <concepts>
#include <cstdint>
#include <functional>
#include <memory>
#include <mutex>
#include <optional>
#include <ostream>
#include <string>
#include <string_view>
#include <utility>
#include <variant>
#include <vector>
 
namespace aria {
 
// ---------------------------------------------------------------------------
//  TraceCategory
// ---------------------------------------------------------------------------

enum class TraceCategory : std::uint8_t {
    Reactive   = 0,   
    Async      = 1,   
    Binding    = 2,   
    Command    = 3,   
    Validation = 4,   
    List       = 5,   
};
 
[[nodiscard]] inline std::string_view to_string(TraceCategory c) noexcept {
    switch (c) {
        case TraceCategory::Reactive:   return "Reactive";
        case TraceCategory::Async:      return "Async";
        case TraceCategory::Binding:    return "Binding";
        case TraceCategory::Command:    return "Command";
        case TraceCategory::Validation: return "Validation";
        case TraceCategory::List:       return "List";
    }
    return "TraceCategory?";
}
 
// ---------------------------------------------------------------------------
//  Per-category event payloads
// ---------------------------------------------------------------------------
//
//  Each category carries a small, focused payload. Adding a new field
//  is a backwards-compatible change (consumers ignore unknown fields);
//  removing a field is breaking and must surface in CHANGELOG.
 
namespace trace {

enum class ReactivePhase : std::uint8_t {
    FlushBegin  = 0,
    RoundBegin  = 1,
    Pull        = 2,
    SkipClean   = 3,
    Recomputed  = 4,
    RoundEnd    = 5,
    FlushEnd    = 6,
};
 
struct Reactive {
    ReactivePhase phase = ReactivePhase::FlushBegin;
    std::string   node_name;
    int           round = 0;
    bool          changed = false;
};

struct Async {
    std::string source;
    std::string op;
    std::uint64_t generation = 0;
};

struct Binding {
    std::string platform;
    std::string target;
    std::string op;
};

struct Command {
    std::string op;
};

struct Validation {
    std::string   op;
    ValidationKey key;
    std::string   message;
};

struct List {
    std::string   op;
    std::size_t   index = 0;
    std::size_t   from_index = 0;   
    std::size_t   size_after = 0;
};
 
}  // namespace trace

using TracePayload = std::variant<
    trace::Reactive,
    trace::Async,
    trace::Binding,
    trace::Command,
    trace::Validation,
    trace::List>;
 
// ---------------------------------------------------------------------------
//  TraceEvent
// ---------------------------------------------------------------------------

struct TraceEvent {
    TraceCategory                  category;
    TracePayload                   payload;
    std::chrono::steady_clock::time_point time =
        std::chrono::steady_clock::now();
    std::optional<::aria::Error>   error;
 
    [[nodiscard]] std::string_view category_name() const noexcept {
        return to_string(category);
    }
};
 
// ---------------------------------------------------------------------------
//  TraceSink
// ---------------------------------------------------------------------------

using TraceSink = std::function<void(const TraceEvent&)>;
 
namespace detail {
 
// Shared trace storage lives in aria_abi, which is linked by core-only
// consumers and platform modules. See modules/abi/src/diagnostics.cpp.
ARIA_ABI_API std::shared_ptr<TraceSink>& global_sink_storage_() noexcept;
ARIA_ABI_API std::mutex& global_sink_mutex_() noexcept;
ARIA_ABI_API std::atomic<bool>& trace_sink_present_() noexcept;
ARIA_ABI_API void dispatch_trace_(const std::shared_ptr<TraceSink>& sink,
                                   const TraceEvent& event) noexcept;

inline std::shared_ptr<TraceSink>
swap_global_sink_(std::shared_ptr<TraceSink> next) noexcept {
    std::lock_guard lk(global_sink_mutex_());
    auto& slot = global_sink_storage_();
    auto prev = std::move(slot);
    slot = std::move(next);
    trace_sink_present_().store(static_cast<bool>(slot), std::memory_order_release);
    return prev;
}

inline std::shared_ptr<TraceSink> snapshot_global_sink_() noexcept {
    std::lock_guard lk(global_sink_mutex_());
    return global_sink_storage_();
}
 
}  // namespace detail
 
// ---------------------------------------------------------------------------
//  Public API: install / clear / publish
// ---------------------------------------------------------------------------

inline void install_trace_sink(TraceSink sink) {
    detail::swap_global_sink_(
        sink ? std::make_shared<TraceSink>(std::move(sink))
             : std::shared_ptr<TraceSink>{});
}

inline void clear_trace_sink() noexcept {
    detail::swap_global_sink_({});
}

[[nodiscard]] inline bool has_trace_sink() noexcept {
    return detail::trace_sink_present_().load(std::memory_order_acquire);
}

inline void publish_trace_unchecked(const TraceEvent& event) noexcept {
    auto sink = detail::snapshot_global_sink_();
    if (sink && *sink) detail::dispatch_trace_(sink, event);
}

inline void publish_trace(const TraceEvent& event) noexcept {
    if (has_trace_sink()) publish_trace_unchecked(event);
}
 
namespace detail {
template<class Payload>
concept TracePayloadType =
    std::same_as<Payload, trace::Reactive> || std::same_as<Payload, trace::Async> ||
    std::same_as<Payload, trace::Binding> || std::same_as<Payload, trace::Command> ||
    std::same_as<Payload, trace::Validation> || std::same_as<Payload, trace::List>;
}  // namespace detail

template<detail::TracePayloadType Payload>
inline void publish_trace_unchecked(TraceCategory category, Payload payload,
                                    std::optional<::aria::Error> error = std::nullopt) {
    auto sink = detail::snapshot_global_sink_();
    if (!sink || !*sink) return;
    const TraceEvent event{category, TracePayload{std::move(payload)},
                           std::chrono::steady_clock::now(), std::move(error)};
    detail::dispatch_trace_(sink, event);
}

template<detail::TracePayloadType Payload>
inline void publish_trace(TraceCategory category, Payload payload,
                          std::optional<::aria::Error> error = std::nullopt) {
    if (has_trace_sink())
        publish_trace_unchecked(category, std::move(payload), std::move(error));
}
 
// ---------------------------------------------------------------------------
//  ScopedTraceSink -- RAII install/restore for tests
// ---------------------------------------------------------------------------

class ScopedTraceSink {
public:
    explicit ScopedTraceSink(TraceSink sink)
        : previous_(detail::swap_global_sink_(
              sink ? std::make_shared<TraceSink>(std::move(sink))
                   : std::shared_ptr<TraceSink>{})) {}
 
    ~ScopedTraceSink() noexcept {
        detail::swap_global_sink_(std::move(previous_));
    }
 
    ScopedTraceSink(const ScopedTraceSink&)            = delete;
    ScopedTraceSink& operator=(const ScopedTraceSink&) = delete;
    ScopedTraceSink(ScopedTraceSink&&)                 = delete;
    ScopedTraceSink& operator=(ScopedTraceSink&&)      = delete;
 
private:
    std::shared_ptr<TraceSink> previous_;
};
 
}  // namespace aria