chronon::observe::ObservationManager

Central singleton coordinating observability setup. More...

#include <ObservationManager.hpp>

Public Classes

	Name
struct	CounterKeyHash
struct	CounterKey Identifies a counter by owning unit and counter ID.

Public Functions

	Name
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.
void	registerCounter(const std::string & unit_name, CounterId id, SimpleCounter * counter_ptr, const std::string & counter_name ="") Register a counter address for later snapshot reading.
void	printReport(std::ostream & out) const
uint64_t	periodicDumpCycles() const
const std::string &	outputDir() const
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	dumpCounterSnapshots(uint64_t cycle) Emit COUNTER_SNAPSHOT events for all registered counters 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.
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 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 registerCounter

void registerCounter(
    const std::string & unit_name,
    CounterId id,
    SimpleCounter * counter_ptr,
    const std::string & counter_name =""
)

Register a counter address for later snapshot reading.

Parameters:

• counter_ptr Pointer to the SimpleCounter in the unit's storage.

function printReport

void printReport(
    std::ostream & out
) const

function periodicDumpCycles

inline uint64_t periodicDumpCycles() const

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

function outputDir

inline const std::string & outputDir() const

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 dumpCounterSnapshots

void dumpCounterSnapshots(
    uint64_t cycle
)

Emit COUNTER_SNAPSHOT events for all registered counters 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 contextCount

size_t contextCount() const

function config

inline const ObservationYAMLConfig & config() const

function backend

inline ObservationBackend * backend()

---

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