Skip to main content

chronon::observe::ObservationManager

Central singleton coordinating observability setup. More...

#include <ObservationManager.hpp>

Public Functions​

Name
booltimelineEnabled() const
True when the backend writes a unified Perfetto timeline (timeline.pftrace).
boolsubmitTimeline(TimelineStreamData && data)
Hand recorded timeline streams to the backend for timeline.pftrace.
voidstopBackend()
Drains remaining events before stopping.
voidstartBackend()
voidshutdown()
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.
voidreset()
Equivalent to shutdown() plus full state clear; intended for tests.
voidreregisterAllCounters()
Re-register all counters from all contexts.
uint16_tregisterSourceName(const std::string & name)
Register a unit name and obtain its source_id.
voidprintReport(std::ostream & out) const
uint64_tperiodicDumpCycles() const
const std::string &outputDir() const
boolisInitialized() const
boolisEnabled() const
boolisBackendRunning() const
ObservationManager &instance()
voidinitialize(const ObservationYAMLConfig & config)
Initialize from YAML config.
std::string_viewgetSourceName(uint16_t source_id) const
Lock-free lookup; returns empty view if not found.
booldumpOnShutdown() const
voiddumpCounterSnapshots(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.
CounterRegistry &counterRegistry()
size_tcontextCount() 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 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 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-06 at 09:03:34 +0000