Skip to main content

chronon::observe::ObservableUnit

More...

#include <ObservableUnit.hpp>

Public Functions​

Name
virtual~ObservableUnit() =default
template <FixedString Fmt,typename... Args>
void		warn(Args &&... args)
template <FixedString Fmt,typename Cat ,typename... Args>
void		trace(Cat category, Args &&... args)
template <FixedString Track>
void		spanEnd()
template <FixedString Track>
void		spanEnd(uint16_t slot)
template <FixedString Track,typename Cat ,typename... Items>
void		spanBegin(Cat category, EventNameRef name, Items &&... items)
template <FixedString Track,typename Cat ,typename... Items>
void		spanBegin(uint16_t slot, Cat category, EventNameRef name, Items &&... items)
voidsetObservationContext(ObservationContext * ctx)
voidregisterTimelineTrack(TimelineTrackBase * track)
voidregisterDerivedCounter(DerivedCounter * dc)
voidregisterCounter(Counter * counter)
template <uint16_t Pipe,FixedString Stage,typename Cat ,typename... Items>
void		pipeStageHex(Cat category, uint64_t id, Items &&... items)
template <FixedString Stage,typename Cat ,typename... Items>
void		pipeStageHex(uint16_t pipe, Cat category, uint64_t id, Items &&... items)
template <uint16_t Pipe,FixedString Stage,typename Cat ,typename... Items>
void		pipeStage(Cat category, uint64_t id, Items &&... items)
template <FixedString Stage,typename Cat ,typename... Items>
void		pipeStage(uint16_t pipe, Cat category, uint64_t id, Items &&... items)
template <uint16_t Pipe,uint16_t Stage,typename Cat ,typename... Items>
void		pipe(Cat category, uint64_t id, Items &&... items)
const ObservationStats &observationStats() const
ObservationContext *observationContext()
const ObservationContext *observationContext() const
boolobservabilityEnabled() const
template <FixedString Track,typename Cat ,typename... Items>
void		instant(Cat category, EventNameRef name, Items &&... items)
template <FixedString Fmt,typename... Args>
void		info(Args &&... args)
virtual uint64_tgetObserveCycle() const
template <FixedString Name,typename T >
void		gauge(T value, std::string_view unit_name ={})
template <FixedString Name,typename Cat ,typename... Items>
void		event(Cat category, Items &&... items)
template <FixedString Fmt,typename... Args>
void		error(Args &&... args)
template <FixedString Fmt,typename... Args>
void		debug(Args &&... args)
template <ObservationChannel Ch>
const ObservationChannelStats &		channelStats() const
template <FixedString Name,typename Used ,typename Capacity >
void		capacity(Used used, Capacity total, std::string_view unit_name ={})

Protected Attributes​

Name
ObservationContext *observe_ctx_

Detailed Description​

class chronon::observe::ObservableUnit;

ObservableUnit - Mixin providing observability to simulation units.

Inherit from this class (in addition to Unit) to add observation capabilities.

Usage:

inline const auto CACHE_HIT = Category<"cache_hit", "Cache hit">{};

class MyUnit : public Unit, public ObservableUnit {
    EventCounter ops_{this, "ops", "Operations executed"};

public:
    void tick() override {
        ++ops_;
        event<"cache_hit">(CACHE_HIT, arg<"addr">(addr));
        debug<"Processing cycle {}">(cycle);
    }
};

Public Functions Documentation​

function ~ObservableUnit​

virtual ~ObservableUnit() =default

function warn​

template <FixedString Fmt,
typename... Args>
inline void warn(
    Args &&... args
)

Emit a warning log message.

function trace​

template <FixedString Fmt,
typename Cat ,
typename... Args>
inline void trace(
    Cat category,
    Args &&... args
)

Parameters:

  • category Trace category
  • args Format arguments

Template Parameters:

  • Fmt Format string (compile-time)

Emit a deprecated text trace event with compile-time format string.

Usage: trace<"I-Cache HIT: pc=0x{:x}">(ICACHE_HIT, pc);

function spanEnd​

template <FixedString Track>
inline void spanEnd()

function spanEnd​

template <FixedString Track>
inline void spanEnd(
    uint16_t slot
)

function spanBegin​

template <FixedString Track,
typename Cat ,
typename... Items>
inline void spanBegin(
    Cat category,
    EventNameRef name,
    Items &&... items
)

Open/close an occupancy span on a named track under this unit.

function spanBegin​

template <FixedString Track,
typename Cat ,
typename... Items>
inline void spanBegin(
    uint16_t slot,
    Cat category,
    EventNameRef name,
    Items &&... items
)

function setObservationContext​

inline void setObservationContext(
    ObservationContext * ctx
)

Set the observation context.

Called by Simulation during unit initialization. Initializes all pending counters.

function registerTimelineTrack​

inline void registerTimelineTrack(
    TimelineTrackBase * track
)

Register a timeline lane/counter for initialization when context is attached.

Called by TimelineTrackBase constructor.

function registerDerivedCounter​

inline void registerDerivedCounter(
    DerivedCounter * dc
)

Register a derived counter for initialization when context is attached.

Called by DerivedCounter constructor.

function registerCounter​

inline void registerCounter(
    Counter * counter
)

Register a counter for initialization when context is attached.

Called by Counter constructor.

function pipeStageHex​

template <uint16_t Pipe,
FixedString Stage,
typename Cat ,
typename... Items>
inline void pipeStageHex(
    Cat category,
    uint64_t id,
    Items &&... items
)

function pipeStageHex​

template <FixedString Stage,
typename Cat ,
typename... Items>
inline void pipeStageHex(
    uint16_t pipe,
    Cat category,
    uint64_t id,
    Items &&... items
)

function pipeStage​

template <uint16_t Pipe,
FixedString Stage,
typename Cat ,
typename... Items>
inline void pipeStage(
    Cat category,
    uint64_t id,
    Items &&... items
)

function pipeStage​

template <FixedString Stage,
typename Cat ,
typename... Items>
inline void pipeStage(
    uint16_t pipe,
    Cat category,
    uint64_t id,
    Items &&... items
)

function pipe​

template <uint16_t Pipe,
uint16_t Stage,
typename Cat ,
typename... Items>
inline void pipe(
    Cat category,
    uint64_t id,
    Items &&... items
)

Emit a first-class pipeline slice whose pipe/stage are compile-time constants. The item id is both the visible Perfetto slice name and the flow id.

function observationStats​

inline const ObservationStats & observationStats() const

Get per-unit observation stats (emitted/dropped per channel).

function observationContext​

inline ObservationContext * observationContext()

Get the observation context.

Returns nullptr if not set (observability disabled).

function observationContext​

inline const ObservationContext * observationContext() const

function observabilityEnabled​

inline bool observabilityEnabled() const

Check if observability is enabled.

function instant​

template <FixedString Track,
typename Cat ,
typename... Items>
inline void instant(
    Cat category,
    EventNameRef name,
    Items &&... items
)

Emit an instant event on a named track under this unit.

function info​

template <FixedString Fmt,
typename... Args>
inline void info(
    Args &&... args
)

Emit an info log message.

function getObserveCycle​

inline virtual uint64_t getObserveCycle() const

Get the current cycle for observation timestamps.

Override this in derived classes to return the unit's local cycle. Default returns 0.

function gauge​

template <FixedString Name,
typename T >
inline void gauge(
    T value,
    std::string_view unit_name ={}
)

Emit push-model counter samples under this unit.

function event​

template <FixedString Name,
typename Cat ,
typename... Items>
inline void event(
    Cat category,
    Items &&... items
)

Emit a low-cardinality instant event on this unit's shared "events" track.

function error​

template <FixedString Fmt,
typename... Args>
inline void error(
    Args &&... args
)

Emit an error log message.

function debug​

template <FixedString Fmt,
typename... Args>
inline void debug(
    Args &&... args
)

Emit a debug log message.

Usage: debug<"Processing request id={}">(request_id);

function channelStats​

template <ObservationChannel Ch>
inline const ObservationChannelStats & channelStats() const

Get stats for a specific observation channel.

function capacity​

template <FixedString Name,
typename Used ,
typename Capacity >
inline void capacity(
    Used used,
    Capacity total,
    std::string_view unit_name ={}
)

Protected Attributes Documentation​

variable observe_ctx_​

ObservationContext * observe_ctx_ = nullptr;

Updated on 2026-07-06 at 09:03:34 +0000