Skip to main content

chronon::observe::BinaryTraceWriter

High-performance binary trace writer using FlatBuffers + optional zstd. More...

#include <BinaryTraceWriter.hpp>

Public Classes​

Name
structFileHeader
Fixed 64-byte file header.

Public Functions​

Name
~BinaryTraceWriter()
voidwriteEvent(const StructuredRecord * record, const std::byte * args_data, size_t args_size)
Buffers an event; blocks are flushed when block_size is exceeded.
voidsetUnitTypeLookup(std::function< std::string_view(uint16_t)> lookup)
voidsetSourceNameLookup(std::function< std::string_view(uint16_t)> lookup)
voidsetSimulationName(std::string name)
BinaryTraceWriter &operator=(const BinaryTraceWriter & ) =delete
boolopen(const std::filesystem::path & path)
Opens path, writes a placeholder header. Schema is written lazily.
boolisOpen() const
voidflush()
uint64_teventsWritten() const
voidclose()
Writes footer and updates header before closing.
uint64_tbytesWritten() const
uint64_tblocksWritten() const
BinaryTraceWriter(const BinaryTraceConfig & config ={})
BinaryTraceWriter(const BinaryTraceWriter & ) =delete

Public Attributes​

Name
uint16_tVERSION_MINOR
v1.1 adds per-event args_size prefix.
uint16_tVERSION_MAJOR
uint32_tMAGIC
"CTRC" little-endian.
uint64_tFLAG_HAS_SCHEMA
uint64_tFLAG_HAS_INDEX
uint64_tFLAG_COMPRESSED
size_tFILE_HEADER_SIZE

Detailed Description​

class chronon::observe::BinaryTraceWriter;

High-performance binary trace writer using FlatBuffers + optional zstd.

File layout: [[FileHeader](/docs/api/Classes/structchronon_1_1observe_1_1BinaryTraceWriter_1_1FileHeader) 64B][Schema FlatBuffer][EventBlock 0]...[EventBlock N][Footer FlatBuffer]. Events buffer in memory and flush as compressed blocks once the buffer exceeds block_size. NOT thread-safe; intended for a single backend thread.

Public Functions Documentation​

function ~BinaryTraceWriter​

~BinaryTraceWriter()

function writeEvent​

void writeEvent(
    const StructuredRecord * record,
    const std::byte * args_data,
    size_t args_size
)

Buffers an event; blocks are flushed when block_size is exceeded.

function setUnitTypeLookup​

inline void setUnitTypeLookup(
    std::function< std::string_view(uint16_t)> lookup
)

function setSourceNameLookup​

inline void setSourceNameLookup(
    std::function< std::string_view(uint16_t)> lookup
)

function setSimulationName​

inline void setSimulationName(
    std::string name
)

function operator=​

BinaryTraceWriter & operator=(
    const BinaryTraceWriter & 
) =delete

function open​

bool open(
    const std::filesystem::path & path
)

Opens path, writes a placeholder header. Schema is written lazily.

function isOpen​

inline bool isOpen() const

function flush​

void flush()

function eventsWritten​

inline uint64_t eventsWritten() const

function close​

void close()

Writes footer and updates header before closing.

function bytesWritten​

inline uint64_t bytesWritten() const

function blocksWritten​

inline uint64_t blocksWritten() const

function BinaryTraceWriter​

explicit BinaryTraceWriter(
    const BinaryTraceConfig & config ={}
)

function BinaryTraceWriter​

BinaryTraceWriter(
    const BinaryTraceWriter & 
) =delete

Public Attributes Documentation​

variable VERSION_MINOR​

static uint16_t VERSION_MINOR = 1;

v1.1 adds per-event args_size prefix.

variable VERSION_MAJOR​

static uint16_t VERSION_MAJOR = 1;

variable MAGIC​

static uint32_t MAGIC = 0x43545243;

"CTRC" little-endian.

variable FLAG_HAS_SCHEMA​

static uint64_t FLAG_HAS_SCHEMA = 1ULL << 2;

variable FLAG_HAS_INDEX​

static uint64_t FLAG_HAS_INDEX = 1ULL << 1;

variable FLAG_COMPRESSED​

static uint64_t FLAG_COMPRESSED = 1ULL << 0;

variable FILE_HEADER_SIZE​

static size_t FILE_HEADER_SIZE = 64;

Updated on 2026-05-26 at 05:42:33 +0000