chronon::observe::ObservationManager

Central singleton coordinating observability setup. More...

#include <ObservationManager.hpp>

Public Functions

	Name
bool	timelineEnabled() const True when the backend writes a unified Perfetto timeline (timeline.pftrace).
bool	submitTimeline(TimelineStreamData && data) Hand recorded timeline streams to the backend for timeline.pftrace.
void	stopBackend() Drains remaining events before stopping.
void	startBackend()
void	shutdown() Stops the backend and releases all resources; initialize() must be called again to reuse.
ObservationQueue *	sharedQueue() Shared queue used for counter snapshots and lookahead commits.
void	reset() Equivalent to shutdown() plus full state clear; intended for tests.
void	reregisterAllCounters() Re-register all counters from all contexts.
uint16_t	registerSourceName(const std::string & name) Register a unit name and obtain its source_id.
bool	pushPeriodicCounterSnapshots(uint64_t cycle, std::span< const size_t > cluster_ids, ThreadContext & producer)
void	printReport(std::ostream & out) const
uint64_t	periodicDumpCycles() const
bool	periodicCounterSnapshotsEnabled() const
ThreadContext *	periodicCounterProducer()
const std::string &	outputDir() const
uint64_t	nextPeriodicCounterCycle(size_t cluster_id, uint64_t run_start, uint64_t period) const Return the next nominal periodic cycle for a stable scheduler cluster.
bool	isInitialized() const
bool	isEnabled() const
bool	isBackendRunning() const
ObservationManager &	instance()
void	initialize(const ObservationYAMLConfig & config) Initialize from YAML config.
std::string_view	getSourceName(uint16_t source_id) const Lock-free lookup; returns empty view if not found.
bool	dumpOnShutdown() const
void	dumpFinalCounterSnapshot(uint64_t cycle) Emit the final COUNTER_SNAPSHOT records at cycle.
ObservationContext *	createContextForUnit(const std::string & unit_name, std::function< uint64_t()> cycle_provider, uint32_t thread_id =0) Create an ObservationContext for a unit.
CounterRegistry &	counterRegistry()
size_t	contextCount() const
const ObservationYAMLConfig &	config() const
ObservationBackend *	backend()

Detailed Description

class chronon::observe::ObservationManager;

Central singleton coordinating observability setup.

Initializes infrastructure from YAML configuration, creates and configures per-unit ObservationContexts, resolves category patterns, and manages backend lifecycle.

auto& obs = ObservationManager::instance();
obs.initialize(config);
auto* ctx = obs.createContextForUnit("my_unit", cycle_provider);
unit->setObservationContext(ctx);
obs.startBackend();
// ... run simulation ...
obs.stopBackend();
obs.shutdown();

Public Functions Documentation

function timelineEnabled

bool timelineEnabled() const

True when the backend writes a unified Perfetto timeline (timeline.pftrace).

function submitTimeline

bool submitTimeline(
    TimelineStreamData && data
)

Hand recorded timeline streams to the backend for timeline.pftrace.

Return: false when the backend is not running or has no timeline sink — the caller should fall back to standalone output.

The streams are written during stopBackend(), after the final event drain.

function stopBackend

void stopBackend()

Drains remaining events before stopping.

function startBackend

void startBackend()

function shutdown

void shutdown()

Stops the backend and releases all resources; initialize() must be called again to reuse.

function sharedQueue

inline ObservationQueue * sharedQueue()

Shared queue used for counter snapshots and lookahead commits.

function reset

void reset()

Equivalent to shutdown() plus full state clear; intended for tests.

function reregisterAllCounters

void reregisterAllCounters()

Re-register all counters from all contexts.

PRECONDITION: all units have been created and their Counters initialized. Counters are added after context creation, so this must be re-run to make them visible for periodic dumps.

function registerSourceName

uint16_t registerSourceName(
    const std::string & name
)

Register a unit name and obtain its source_id.

Return: 1-based source ID (0 reserved for "unknown").

function pushPeriodicCounterSnapshots

bool pushPeriodicCounterSnapshots(
    uint64_t cycle,
    std::span< const size_t > cluster_ids,
    ThreadContext & producer
)

Push counters owned by scheduler clusters to the worker's SPSC queue.

No manager or queue mutex is taken. The caller must be the sole writer of every supplied cluster and must not race manager reconfiguration.

function printReport

void printReport(
    std::ostream & out
) const

function periodicDumpCycles

inline uint64_t periodicDumpCycles() const

Return: Dump interval in cycles (0 = disabled).

function periodicCounterSnapshotsEnabled

inline bool periodicCounterSnapshotsEnabled() const

True only when periodic counter records have an enabled consumer. The configuration is immutable while a simulation is running, so this control-plane query needs no synchronization.

function periodicCounterProducer

ThreadContext * periodicCounterProducer()

Exceptions:

• std::runtime_error if the bounded producer pool is exhausted.

Return the calling scheduler worker's lock-free observation producer context. Called once before a worker enters its execution loop.

function outputDir

inline const std::string & outputDir() const

function nextPeriodicCounterCycle

uint64_t nextPeriodicCounterCycle(
    size_t cluster_id,
    uint64_t run_start,
    uint64_t period
) const

Return the next nominal periodic cycle for a stable scheduler cluster.

function isInitialized

inline bool isInitialized() const

function isEnabled

inline bool isEnabled() const

function isBackendRunning

bool isBackendRunning() const

function instance

static ObservationManager & instance()

function initialize

void initialize(
    const ObservationYAMLConfig & config
)

Initialize from YAML config.

Creates the shared queue and backend; does not start the backend yet.

function getSourceName

std::string_view getSourceName(
    uint16_t source_id
) const

Lock-free lookup; returns empty view if not found.

function dumpOnShutdown

inline bool dumpOnShutdown() const

function dumpFinalCounterSnapshot

void dumpFinalCounterSnapshot(
    uint64_t cycle
)

Emit the final COUNTER_SNAPSHOT records at cycle.

Uses the registration-based pull model: reads from registered counter addresses rather than iterating context storage. Thread-safe.

function createContextForUnit

ObservationContext * createContextForUnit(
    const std::string & unit_name,
    std::function< uint64_t()> cycle_provider,
    uint32_t thread_id =0
)

Create an ObservationContext for a unit.

Return: Non-owning pointer; ObservationManager owns the context.

The context is configured with global YAML settings, per-unit overrides, and category temporal filters.

function counterRegistry

inline CounterRegistry & counterRegistry()

function contextCount

size_t contextCount() const

function config

inline const ObservationYAMLConfig & config() const

function backend

inline ObservationBackend * backend()

---

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