Skip to main content
Version: 2.5.0

Core Concepts

This page provides detailed definitions of ChronoLog's core data model concepts. For a high-level overview, see the Overview.

Conceptual Hierarchy​

CONCEPTUAL HIERARCHYChronicleclient-level namespace / containerStoryclient-level time-series datasetStoryChunkservice-internal time-windowed event batchEventclient-visible individual recordstoryIdeventTimeclientIdeventIndexlogRecord (application payload)ArchiveArchiveArchiveArchiveordered by EventSequence (eventTime, clientId, eventIndex)

Client-facing developers primarily interact with Chronicle, Story, and Event. System and infrastructure developers also work with internal concepts such as StoryChunk and Archive.

Client-Level Concepts​

Chronicle​

A Chronicle is the top-level organizational unit in ChronoLog — a named container that groups related Stories together for easier data management. Each Chronicle is uniquely identified by a numeric ChronicleId, computed as CityHash64(chronicleName). This deterministic hashing means that any process in the distributed system can independently derive the same ID from the same name without coordination.

Chronicles expose configurable attributes including indexing granularity (nanoseconds through seconds), type (standard or priority), and tiering policy (normal, hot, or cold). In ChronoLog v2.5.0, these Chronicle-level attributes are accepted but do not affect runtime behavior yet. Chronicles also support user-defined properties and metadata, each capped at 16 entries.

Story names are scoped within their parent Chronicle, so two different Chronicles may each contain a Story with the same name without conflict. The Chronicle maintains an acquisition reference count that tracks how many clients are currently using it.

Story​

A Story is a time-series dataset within a Chronicle. It represents a logical stream of events that client applications generate over time. Each Story is uniquely identified by a StoryId, computed as CityHash64(chronicleName + storyName). Concatenating the Chronicle name ensures that identically named Stories in different Chronicles receive distinct IDs.

Stories expose configurable attributes for indexing granularity, type, tiering policy, and access permission. In ChronoLog v2.5.0, these Story-level attributes are accepted but do not affect runtime behavior yet.

The ChronoVisor maintains an in-memory representation of each Story that tracks which clients have acquired (are actively writing to) the Story. This acquirer client map is protected by a mutex for thread-safe concurrent access. The Story's acquisition count acts as a reference counter — a Story cannot be removed while any client holds it.

Event​

An Event is the atomic data unit in ChronoLog. Every piece of data stored in the system is represented as an Event. Each event carries five fields: the storyId identifying which Story it belongs to, an eventTime timestamp, the clientId of the application that generated it, an eventIndex (per-client counter to disambiguate events with identical timestamps), and a logRecord containing the opaque application payload.

Events are globally ordered by a composite key called EventSequence, which is the tuple (eventTime, clientId, eventIndex). This three-part key is essential for distributed uniqueness: because multiple clients on different HPC nodes may generate events at the same timestamp, the clientId component distinguishes them. The eventIndex further handles the case where the same client produces multiple events within a single timestamp granularity (e.g., from different threads). Equality comparison checks all identifying fields (storyId, eventTime, clientId, eventIndex) but deliberately excludes the logRecord payload.

Service-Internal Concepts​

StoryChunk​

A StoryChunk is a container for Events that fall within a specific time window [startTime, endTime) — including the start time and excluding the end time. Events within a StoryChunk are stored in a sorted map keyed by EventSequence, ensuring they are always maintained in global order.

StoryChunks are the unit of data movement through the distributed pipeline. ChronoKeeper processes on compute nodes collect events into StoryChunks during a configurable acceptance window. When the window expires, the StoryChunk is forwarded to a ChronoGrapher process on a storage node. Because multiple ChronoKeepers may handle events for the same Story, each produces a partial StoryChunk for overlapping time ranges. The ChronoGrapher merges these partial chunks into its own StoryPipeline — a sequence of StoryChunks ordered by start time.

Each StoryChunk also carries a revisionTime field that records when it was last modified, enabling the system to track data freshness during the merge process.

Archive​

An Archive provides historical storage associated with a Chronicle. Each Archive is identified by an ArchiveId, computed as CityHash64(toString(chronicleId) + archiveName). Archives carry a user-defined property list for application-specific metadata. The list has no effect so far in ChronoLog v2.5.0.