Skip to main content

chronon::observe

Namespaces​

Name
chronon::observe::timeline_observe_detail
chronon::observe::timeline_detail
chronon::observe::timeline_arg_detail
chronon::observe::simd
chronon::observe::pipeline_detail
chronon::observe::observe_detail
chronon::observe::counter_detail
chronon::observe::category
chronon::observe::DerivedFormula
Convenience formulas for common derived-counter patterns.

Classes​

Name
structchronon::observe::ArgTypeOf< uint8_t >
structchronon::observe::ArgTypeOf< uint64_t >
structchronon::observe::ArgTypeOf< uint32_t >
structchronon::observe::ArgTypeOf< uint16_t >
structchronon::observe::ArgTypeOf< int8_t >
structchronon::observe::ArgTypeOf< int64_t >
structchronon::observe::ArgTypeOf< int32_t >
structchronon::observe::ArgTypeOf< int16_t >
structchronon::observe::ArgTypeOf< float >
structchronon::observe::ArgTypeOf< double >
structchronon::observe::ArgTypeOf< const char * >
structchronon::observe::ArgTypeOf< char * >
structchronon::observe::ArgTypeOf< bool >
structchronon::observe::ArgTypeOf< T * >
structchronon::observe::ArgTypeOf
Maps a C++ type to its ArgType.
structchronon::observe::ArenaSnapshot
Copy of the arena region referenced by a batch of flushed records.
classchronon::observe::AnnotationValueRegistry
Global registry of typed-annotation string values.
classchronon::observe::AnnotationKeyRegistry
Global registry of typed-annotation key names (arg<"addr">).
structchronon::observe::AnnotationKey
Each distinct annotation key registers once (function-local static).

Types​

Name
enum class uint8_tTimelineEventKind { SpanEnd = 2, SpanBegin = 1, PipelineSlice = 4, Instant = 0, CounterSample = 3}
enum class uint8_tTimelineArgKind { Uint = 0, String = 5, Pointer = 4, Int = 1, Double = 2, Bool = 3}
Value categories for typed annotation args (normalized at the producer).
enum class uint8_tObservationChannel { Warn = 3, Trace = 0, NumChannels = 5, Info = 2, Error = 4, Debug = 1}
Identifies the observation channel for per-unit stats tracking.
enum class uint8_tLogLevel { Warn = 2, Info = 1, Error = 3, Debug = 0}
using uint32_tFormatId
Compile-time format-string registration for zero-copy trace/log.
enum class uint32_tCounterId { }
Strongly typed counter identifier; indexes into the counter storage array.
enum class uint8_tCounterCsvFormat { Pivoted, Long}
Counter CSV layout.
using std::function< double(std::span< const uint64_t >)>ComputeFn
using uint64_tCategoryMask
Bitmask for observability categories.
enum class uint8_tBackpressurePolicy { SpinWait, Drop, BoundedWait}
Producer behavior when SPSC queues are full.
enum class uint8_tArgType { UInt8, UInt64, UInt32, UInt16, String, Pointer, None = 0, Int8, Int64, Int32, Int16, Float, Double, Bool}

Functions​

Name
voidwriteTimeline(PerfettoTraceWriter & writer, const TimelineStreamData & data)
Emit data as complete slices under a dedicated process group track.
TimelineArgValueunpackTimelineArg(const std::byte * src)
template <FixedString Fmt,typename Cat ,typename... Args>
void		trace(ObservationContext * ctx, Cat category, Args &&... args)
Emit a deprecated text trace event with compile-time format string.
uint32_ttoIndex(CounterId id)
uint64_ttimelineLocalStringId(uint64_t id)
template <FixedString Track,typename Unit >
void		spanEnd(Unit & unit)
template <FixedString Track,typename Unit >
void		spanEnd(Unit & unit, uint16_t slot)
template <FixedString Track,typename Unit ,typename Cat ,typename... Items>
void		spanBegin(Unit & unit, Cat category, EventNameRef name, Items &&... items)
Begin/end named occupancy spans without declaring a TimelineLane member.
template <FixedString Track,typename Unit ,typename Cat ,typename... Items>
void		spanBegin(Unit & unit, uint16_t slot, Cat category, EventNameRef name, Items &&... items)
template <FixedString Name,typename Unit ,typename Port >
void		portRemaining(Unit & unit, const Port & port, std::string_view unit_name ="sends")
template <FixedString Name,typename Unit ,typename Port >
void		portAvailable(Unit & unit, const Port & port, std::string_view unit_name ="entries")
std::stringpipelineColoredEventName(std::string_view visible_name, uint64_t color_hash)
uint64_tpipelineColorHash(uint64_t id)
uint64_tpipelineColorHash(std::string_view key)
std::stringpipelineColorCategory(uint64_t color_hash)
template <uint16_t Pipe,FixedString Stage,typename Cat ,typename... Items>
void		pipeStageHex(ObservationContext * ctx, Cat category, uint64_t id, Items &&... items)
template <FixedString Stage,typename Cat ,typename... Items>
void		pipeStageHex(ObservationContext * ctx, uint16_t pipe, Cat category, uint64_t id, Items &&... items)
template <uint16_t Pipe,FixedString Stage,typename Cat ,typename... Items>
void		pipeStage(ObservationContext * ctx, Cat category, uint64_t id, Items &&... items)
template <FixedString Stage,typename Cat ,typename... Items>
void		pipeStage(ObservationContext * ctx, uint16_t pipe, Cat category, uint64_t id, Items &&... items)
template <uint16_t Pipe>
PipelinePipe< Pipe >		pipe()
template <uint16_t Pipe,uint16_t Stage,typename Cat ,typename... Items>
void		pipe(ObservationContext * ctx, Cat category, uint64_t id, Items &&... items)
voidpackTimelineArg(std::byte * dest, const TimelineArgValue & arg)
template <FixedString Name>
EventNameRef		operator""_ev()
template <typename T >
TimelineArgValue		normalizeTimelineArg(const TypedArg< T > & a)
Normalizes a typed arg to its wire representation.
uint64_tmakeTimelineLocalStringId(uint64_t id)
CounterIdmakeCounterId(uint32_t value)
template <FixedString Fmt,typename... Args>
void		log_warn(ObservationContext * ctx, Args &&... args)
template <FixedString Fmt,typename... Args>
void		log_info(ObservationContext * ctx, Args &&... args)
template <FixedString Fmt,typename... Args>
void		log_error(ObservationContext * ctx, Args &&... args)
template <FixedString Fmt,typename... Args>
void		log_debug(ObservationContext * ctx, Args &&... args)
CategoryMasklogLevelToCategory(LogLevel level)
template <LogLevel Level,FixedString Fmt,typename... Args>
void		log(ObservationContext * ctx, Args &&... args)
boolisTimelineLocalStringId(uint64_t id)
template <FixedString Track,typename Unit ,typename Cat ,typename... Items>
void		instant(Unit & unit, Cat category, EventNameRef name, Items &&... items)
Emit an instant event on a named track.
template <FixedString Name,typename Unit ,typename T >
void		gauge(Unit & unit, T value, std::string_view unit_name ={})
Emit one push-model counter sample on a named Perfetto counter track.
template <FixedString Name,typename Unit ,typename Cat ,typename T >
void		gauge(Unit & unit, Cat category, T value, std::string_view unit_name ={})
std::stringformatArgToString(const std::byte * data, ArgType type, bool hex)
Format a typed argument to a string using snprintf.
Flowflow(uint64_t id)
template <FixedString Name,typename Unit ,typename Cat ,typename... Items>
void		event(Unit & unit, Cat category, Items &&... items)
Emit a low-cardinality instant event on the unit's shared "events" track.
template <FixedString Name,typename Unit ,typename Used ,typename Capacity >
void		capacity(Unit & unit, Used used, Capacity total, std::string_view unit_name ={})
Emit used/free capacity samples on sibling counter tracks.
template <FixedString Name,typename Unit ,typename Cat ,typename Used ,typename Capacity >
void		capacity(Unit & unit, Cat category, Used used, Capacity total, std::string_view unit_name ={})
size_targSize(ArgType type, const std::byte * data, const std::byte * end)
Compute the byte size of a serialized argument of the given type.
template <FixedString Key,typename T >
TypedArg< T >		arg(T value)
template <size_t N>
FixedString(const char(&)[N])

Attributes​

Name
ObservationChannellog_level_channel_v
uint8_tTIMELINE_NO_CATEGORY
Fixed-size queue record for timeline events.
uint64_tTIMELINE_LOCAL_STRING_ID_BIT
uint8_tTIMELINE_FLAG_NAME_HEX
size_tTIMELINE_ARG_SIZE
On-the-wire arg size: [bits u64][key_id u16][kind u8][pad u8].
size_tMAX_TIMELINE_ARGS
size_tMAX_FORMAT_ARGS
FormatIdINVALID_FORMAT_ID

Types Documentation​

enum TimelineEventKind​

EnumeratorValueDescription
SpanEnd2
SpanBegin1
PipelineSlice4One-cycle pipeline occupancy slice; payload is item id.
Instant0
CounterSample3

enum TimelineArgKind​

EnumeratorValueDescription
Uint0
String5
Pointer4
Int1
Double2
Bool3

Value categories for typed annotation args (normalized at the producer).

enum ObservationChannel​

EnumeratorValueDescription
Warn3
Trace0
NumChannels5
Info2
Error4
Debug1

Identifies the observation channel for per-unit stats tracking.

enum LogLevel​

EnumeratorValueDescription
Warn2
Info1
Error3
Debug0

using FormatId​

using chronon::observe::FormatId =  uint32_t;

Compile-time format-string registration for zero-copy trace/log.

Format strings are registered at static-initialization time and assigned a unique 32-bit ID; the runtime transmits only ID + arg values, and the backend thread reconstructs formatted messages.

enum CounterId​

EnumeratorValueDescription

Strongly typed counter identifier; indexes into the counter storage array.

enum CounterCsvFormat​

EnumeratorValueDescription
Pivoted
Long

Counter CSV layout.

  • Long: One row per (cycle, unit, counter, value); streaming-friendly.
  • Pivoted: Rows are cycles, columns are counters; compact and readable.

using ComputeFn​

using chronon::observe::ComputeFn =  std::function<double(std::span<const uint64_t>)>;

Receives snapshotted delta values for each source counter (declaration order) and returns the derived value. Invoked on the backend thread at CSV dump time.

using CategoryMask​

using chronon::observe::CategoryMask =  uint64_t;

Bitmask for observability categories.

Bits 0-7 are reserved for built-in categories (counters, trace, log levels); bits 8-63 are user-defined unit-specific categories.

enum BackpressurePolicy​

EnumeratorValueDescription
SpinWait
Drop
BoundedWait

Producer behavior when SPSC queues are full.

  • Drop: Drop immediately when queue full (zero stall, data loss).
  • SpinWait: Spin indefinitely until space available (zero data loss, may stall).
  • BoundedWait: Spin up to max_spins iterations, then drop (recommended default).

enum ArgType​

EnumeratorValueDescription
UInt8
UInt64
UInt32
UInt16
String
Pointer
None0
Int8
Int64
Int32
Int16
Float
Double
Bool

Functions Documentation​

function writeTimeline​

void writeTimeline(
    PerfettoTraceWriter & writer,
    const TimelineStreamData & data
)

Emit data as complete slices under a dedicated process group track.

function unpackTimelineArg​

inline TimelineArgValue unpackTimelineArg(
    const std::byte * src
)

function trace​

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

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

trace<"Cache HIT: addr=0x{:x}">(ctx, CACHE_HIT, addr);

function toIndex​

uint32_t toIndex(
    CounterId id
)

function timelineLocalStringId​

inline uint64_t timelineLocalStringId(
    uint64_t id
)

function spanEnd​

template <FixedString Track,
typename Unit >
inline void spanEnd(
    Unit & unit
)

function spanEnd​

template <FixedString Track,
typename Unit >
inline void spanEnd(
    Unit & unit,
    uint16_t slot
)

function spanBegin​

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

Begin/end named occupancy spans without declaring a TimelineLane member.

function spanBegin​

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

function portRemaining​

template <FixedString Name,
typename Unit ,
typename Port >
inline void portRemaining(
    Unit & unit,
    const Port & port,
    std::string_view unit_name ="sends"
)

function portAvailable​

template <FixedString Name,
typename Unit ,
typename Port >
inline void portAvailable(
    Unit & unit,
    const Port & port,
    std::string_view unit_name ="entries"
)

function pipelineColoredEventName​

std::string pipelineColoredEventName(
    std::string_view visible_name,
    uint64_t color_hash
)

function pipelineColorHash​

uint64_t pipelineColorHash(
    uint64_t id
)

function pipelineColorHash​

uint64_t pipelineColorHash(
    std::string_view key
)

function pipelineColorCategory​

std::string pipelineColorCategory(
    uint64_t color_hash
)

function pipeStageHex​

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

function pipeStageHex​

template <FixedString Stage,
typename Cat ,
typename... Items>
inline void pipeStageHex(
    ObservationContext * ctx,
    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(
    ObservationContext * ctx,
    Cat category,
    uint64_t id,
    Items &&... items
)

function pipeStage​

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

function pipe​

template <uint16_t Pipe>
PipelinePipe< Pipe > pipe()

function pipe​

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

function packTimelineArg​

inline void packTimelineArg(
    std::byte * dest,
    const TimelineArgValue & arg
)

function operator""_ev​

template <FixedString Name>
inline EventNameRef operator""_ev()

function normalizeTimelineArg​

template <typename T >
inline TimelineArgValue normalizeTimelineArg(
    const TypedArg< T > & a
)

Normalizes a typed arg to its wire representation.

function makeTimelineLocalStringId​

inline uint64_t makeTimelineLocalStringId(
    uint64_t id
)

function makeCounterId​

CounterId makeCounterId(
    uint32_t value
)

function log_warn​

template <FixedString Fmt,
typename... Args>
inline void log_warn(
    ObservationContext * ctx,
    Args &&... args
)

function log_info​

template <FixedString Fmt,
typename... Args>
inline void log_info(
    ObservationContext * ctx,
    Args &&... args
)

function log_error​

template <FixedString Fmt,
typename... Args>
inline void log_error(
    ObservationContext * ctx,
    Args &&... args
)

function log_debug​

template <FixedString Fmt,
typename... Args>
inline void log_debug(
    ObservationContext * ctx,
    Args &&... args
)

function logLevelToCategory​

CategoryMask logLevelToCategory(
    LogLevel level
)

function log​

template <LogLevel Level,
FixedString Fmt,
typename... Args>
inline void log(
    ObservationContext * ctx,
    Args &&... args
)

function isTimelineLocalStringId​

inline bool isTimelineLocalStringId(
    uint64_t id
)

function instant​

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

Emit an instant event on a named track.

function gauge​

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

Emit one push-model counter sample on a named Perfetto counter track.

function gauge​

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

function formatArgToString​

inline std::string formatArgToString(
    const std::byte * data,
    ArgType type,
    bool hex
)

Format a typed argument to a string using snprintf.

This is the portable formatting path for consumers that do not depend on fmt.

function flow​

inline Flow flow(
    uint64_t id
)

function event​

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

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

The event name is a compile-time literal and details are typed annotations: observe::event<"flush">(*this, CAT, arg<"removed">(n)).

function capacity​

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

Emit used/free capacity samples on sibling counter tracks.

function capacity​

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

function argSize​

inline size_t argSize(
    ArgType type,
    const std::byte * data,
    const std::byte * end
)

Compute the byte size of a serialized argument of the given type.

For fixed-size types, the size is known statically. For strings, scans forward to the null terminator.

function arg​

template <FixedString Key,
typename T >
inline TypedArg< T > arg(
    T value
)

function FixedString​

template <size_t N>
FixedString(
    const  char(&)[N]
)

Attributes Documentation​

variable log_level_channel_v​

ObservationChannel log_level_channel_v = LogLevelToChannel<L>::value;

variable TIMELINE_NO_CATEGORY​

uint8_t TIMELINE_NO_CATEGORY = 0xFF;

Fixed-size queue record for timeline events.

Layout in queue: [RecordHeader][TimelineRecord][arg0]...[argN-1], where each arg is TIMELINE_ARG_SIZE bytes (see packTimelineArg). cycle MUST stay the first uint64_t: ReorderBuffer::extractCycle and the drain loop's watermark peek read it positionally. Sentinel for TimelineRecord::category_bit: no user category.

variable TIMELINE_LOCAL_STRING_ID_BIT​

uint64_t TIMELINE_LOCAL_STRING_ID_BIT = 1ULL << 63;

variable TIMELINE_FLAG_NAME_HEX​

uint8_t TIMELINE_FLAG_NAME_HEX = 1u << 0;

variable TIMELINE_ARG_SIZE​

size_t TIMELINE_ARG_SIZE = 12;

On-the-wire arg size: [bits u64][key_id u16][kind u8][pad u8].

variable MAX_TIMELINE_ARGS​

size_t MAX_TIMELINE_ARGS = 8;

variable MAX_FORMAT_ARGS​

size_t MAX_FORMAT_ARGS = 8;

variable INVALID_FORMAT_ID​

FormatId INVALID_FORMAT_ID = 0;

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