Timeline Architecture

Query and presentation service for HLC-ordered cross-service event timelines.

Overview

Timeline provides a REST API for querying, analyzing, and replaying events that have been indexed by the TimelineIndexer module. All events carry Hybrid Logical Clock (HLC) timestamps that establish causal ordering across distributed services. The service supports correlation-based queries, critical path analysis for latency diagnosis, service-scoped views, and deterministic event replay.

Components

src/Timeline/
  StellaOps.Timeline.WebService/        # REST API (ASP.NET Core)
    Endpoints/
      TimelineEndpoints.cs              # Core timeline query endpoints
      ExportEndpoints.cs                # Event export endpoints
      ReplayEndpoints.cs                # Deterministic replay endpoints
    Program.cs                          # Host configuration
  StellaOps.Timeline.Core/              # Query service and models
    ITimelineQueryService.cs            # Core query interface
    TimelineQueryService.cs             # Query implementation
    Models/
      TimelineEvent.cs                  # Event with HLC timestamp + correlation ID
      CriticalPathResult.cs             # Stages with durations
      TimelineQueryOptions.cs           # Filters + pagination

Data Flow

Events are produced by various Stella Ops services and carry HLC timestamps.
TimelineIndexer (separate module) ingests and indexes these events into the event store.
Timeline WebService receives query requests from Platform, CLI, Web, or Replay.
Timeline Core executes queries against the indexed event store, applying correlation, service, and time-range filters.
Results are returned in HLC-sorted order, with optional critical path analysis computing latency stages between correlated events.

Database Schema

Timeline reads from the event store managed by the Eventing infrastructure (PostgreSQL). Key columns queried:

Column	Type	Description
`event_id`	UUID	Unique event identifier
`hlc_timestamp`	BIGINT	Hybrid Logical Clock timestamp
`correlation_id`	VARCHAR	Cross-service correlation identifier
`service`	VARCHAR	Originating service name
`event_type`	VARCHAR	Event type discriminator
`payload`	JSONB	Event payload
`created_at`	TIMESTAMPTZ	Wall-clock ingestion time

Dependencies

Service/Library	Purpose
StellaOps.Eventing	Event store access and query primitives
StellaOps.HybridLogicalClock	HLC timestamp parsing and comparison
Router	Service mesh routing and discovery
Authority	JWT/OAuth token validation

Endpoints

Method	Path	Description
GET	`/timeline/by-correlation/{correlationId}`	Query events by correlation ID (HLC-ordered)
GET	`/timeline/critical-path/{correlationId}`	Critical path analysis with latency stages
GET	`/timeline/by-service/{service}`	Service-filtered timeline view
POST	`/timeline/export`	Export events matching query criteria
POST	`/timeline/replay`	Deterministic replay of an event sequence

Security Considerations

Authentication: All endpoints require a valid JWT issued by Authority.
Tenant isolation: Queries are scoped to the authenticated tenant; cross-tenant event access is prohibited.
Read-only surface: Timeline exposes only read and replay operations. Event mutation is handled exclusively by TimelineIndexer.
Export controls: Exported event payloads may contain sensitive operational data; exports are audit-logged.
Replay determinism: Replay operations produce identical output given identical input sequences, supporting audit and compliance verification.

Relationship to TimelineIndexer

Timeline and TimelineIndexer are separate deployable services with distinct responsibilities:

TimelineIndexer: Consumes events from the message bus, assigns HLC timestamps, and writes indexed events to the event store.
Timeline: Reads from the event store and serves query, analysis, export, and replay requests.

This separation allows independent scaling of ingestion and query workloads.

4.9 KiB Raw Blame History