Skip to main content

chronon::observe::ObservationBackend

Background worker that drains observability queues and writes output files. More...

#include <ObservationBackend.hpp>

Public Classes​

Name
structConfig

Public Types​

Name
using std::function< void(ObservationQueue::EventType type, const std::byte *data, size_t size)>EventHandler

Public Functions​

Name
~ObservationBackend()
voidwakeUp()
Set the wake flag; the spin-wait loop picks it up. Safe from any producer.
booltimelineEnabled() const
voidsubmitTimeline(TimelineStreamData && data)
Submit recorded timeline streams for inclusion in timeline.pftrace.
voidstop()
Drains remaining events before stopping.
voidstart()
voidsetStopToken(stdexec::inplace_stop_token token)
Set an optional observation-lifetime stop token.
voidsetSourceNameLookup(std::function< std::string_view(uint16_t)> lookup)
voidsetLogHandler(EventHandler handler)
voidsetDerivedCounterDefs(std::vector< DerivedCounterDef > defs)
voidsetCounterSnapshotPlans(std::vector< CounterSnapshotPlanMetadata > plans)
voidsetCounterColumns(std::vector< CounterSnapshotEntryMetadata > columns)
const std::filesystem::path &outputDir() const
ObservationBackend &operator=(const ObservationBackend & ) =delete
boolisRunning() const
uint64_teventsProcessed() const
uint64_tbytesWritten() const
ObservationBackend(ObservationQueue & queue)
ObservationBackend(ObservationQueue & queue, const Config & config)
ObservationBackend(const ObservationBackend & ) =delete

Friends​

Name
structObservationBackendTestAccess

Detailed Description​

class chronon::observe::ObservationBackend;

Background worker that drains observability queues and writes output files.

Drains per-thread SPSC queues (traces/logs) and the shared queue (counter snapshots, lookahead commits), then routes each event to the text and/or Perfetto timeline sinks.

Output files:

  • events.log — text output (debug/info/warn/error, optional trace mirror).
  • timeline.pftrace — Perfetto timeline (unit events, counter tracks, and the scheduler execution timeline submitted at shutdown).
  • counters.csv — performance counter snapshots.

Public Types Documentation​

using EventHandler​

using chronon::observe::ObservationBackend::EventHandler = 
        std::function<void(ObservationQueue::EventType type, const std::byte* data, size_t size)>;

Public Functions Documentation​

function ~ObservationBackend​

~ObservationBackend()

function wakeUp​

void wakeUp()

Set the wake flag; the spin-wait loop picks it up. Safe from any producer.

function timelineEnabled​

inline bool timelineEnabled() const

True when this backend has an open Perfetto timeline sink. Reports false when the timeline is disabled by config or the file failed to open, so callers (scheduler timeline handoff) can fall back to standalone output.

function submitTimeline​

void submitTimeline(
    TimelineStreamData && data
)

Submit recorded timeline streams for inclusion in timeline.pftrace.

Thread-safe; intended for end-of-run handoff (e.g. the scheduler execution timeline). The data is written by the worker thread during stop(), after the final event drain, so callers must submit before stopping the backend.

function stop​

void stop()

Drains remaining events before stopping.

function start​

void start()

function setStopToken​

inline void setStopToken(
    stdexec::inplace_stop_token token
)

Set an optional observation-lifetime stop token.

Do not pass the simulation worker token: final records are submitted after workers terminate. PRECONDITION: must be called before start().

function setSourceNameLookup​

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

function setLogHandler​

inline void setLogHandler(
    EventHandler handler
)

function setDerivedCounterDefs​

void setDerivedCounterDefs(
    std::vector< DerivedCounterDef > defs
)

Called by ObservationManager before start(). Definitions are resolved to column indices once raw counter columns are finalized.

function setCounterSnapshotPlans​

void setCounterSnapshotPlans(
    std::vector< CounterSnapshotPlanMetadata > plans
)

Register immutable counter names once; periodic records then carry only values. PRECONDITION: called before start().

function setCounterColumns​

void setCounterColumns(
    std::vector< CounterSnapshotEntryMetadata > columns
)

Register the complete raw counter schema, including contexts that only contribute legacy/final snapshots and therefore have no periodic plan. PRECONDITION: called before start().

function outputDir​

inline const std::filesystem::path & outputDir() const

function operator=​

ObservationBackend & operator=(
    const ObservationBackend & 
) =delete

function isRunning​

inline bool isRunning() const

function eventsProcessed​

inline uint64_t eventsProcessed() const

function bytesWritten​

inline uint64_t bytesWritten() const

function ObservationBackend​

explicit ObservationBackend(
    ObservationQueue & queue
)

function ObservationBackend​

explicit ObservationBackend(
    ObservationQueue & queue,
    const Config & config
)

function ObservationBackend​

ObservationBackend(
    const ObservationBackend & 
) =delete

Friends​

friend ObservationBackendTestAccess​

friend struct ObservationBackendTestAccess(
    ObservationBackendTestAccess 
);

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