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::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 = 3, Instant = 0}
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)
uint32_ttoIndex(CounterId id)
uint64_ttimelineLocalStringId(uint64_t id)
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)
std::stringformatArgToString(const std::byte * data, ArgType type, bool hex)
Format a typed argument to a string using snprintf.
Flowflow(uint64_t id)
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
uint8_tCOUNTER_SNAPSHOT_BATCH_FLAG
COUNTER_SNAPSHOT record flag: payload is one metadata-indexed value batch.

Types Documentation​

enum TimelineEventKind​

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

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 toIndex​

uint32_t toIndex(
    CounterId id
)

function timelineLocalStringId​

inline uint64_t timelineLocalStringId(
    uint64_t id
)

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 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 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;

variable COUNTER_SNAPSHOT_BATCH_FLAG​

uint8_t COUNTER_SNAPSHOT_BATCH_FLAG = 1u << 1;

COUNTER_SNAPSHOT record flag: payload is one metadata-indexed value batch.

Updated on 2026-07-23 at 16:24:33 +0000