consolidation of some of the modules, localization fixes, product advisories work, qa work
This commit is contained in:
master
@@ -10,29 +10,54 @@ Timeline provides a REST API for querying, analyzing, and replaying events that
|
||||
|
||||
```
|
||||
src/Timeline/
|
||||
StellaOps.Timeline.WebService/ # REST API (ASP.NET Core)
|
||||
StellaOps.Timeline.WebService/ # Timeline REST API (ASP.NET Core)
|
||||
Audit/ # Unified audit contracts, provider, and aggregation service
|
||||
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
|
||||
TimelineEndpoints.cs # Core timeline query endpoints
|
||||
ExportEndpoints.cs # Event export endpoints
|
||||
ReplayEndpoints.cs # Deterministic replay endpoints
|
||||
UnifiedAuditEndpoints.cs # Unified /api/v1/audit aggregation endpoints
|
||||
Program.cs # Host configuration
|
||||
StellaOps.TimelineIndexer.WebService/ # Indexer REST API (ASP.NET Core)
|
||||
Program.cs # Host configuration
|
||||
TimelineAuthorizationAuditSink.cs # Authorization audit sink
|
||||
StellaOps.TimelineIndexer.Worker/ # Background ingestion worker (separately deployable)
|
||||
TimelineIngestionWorker.cs # Background event ingestion
|
||||
Program.cs # Worker host configuration
|
||||
__Libraries/
|
||||
StellaOps.Timeline.Core/ # Query service and models
|
||||
ITimelineQueryService.cs # Core query interface
|
||||
TimelineQueryService.cs # Query implementation
|
||||
StellaOps.TimelineIndexer.Core/ # Ingestion domain logic
|
||||
Abstractions/ # ITimelineEventStore, ITimelineIngestionService, etc.
|
||||
Models/ # TimelineEventEnvelope, TimelineEventView, etc.
|
||||
Services/ # TimelineIngestionService, TimelineQueryService
|
||||
StellaOps.TimelineIndexer.Infrastructure/ # Persistence, EfCore, messaging subscribers
|
||||
Db/ # Migrations, event store, query store
|
||||
EfCore/ # Compiled models, context, entity models
|
||||
Subscriptions/ # NATS, Redis, Null subscribers
|
||||
__Tests/
|
||||
StellaOps.Timeline.Core.Tests/ # Timeline query tests
|
||||
StellaOps.Timeline.WebService.Tests/ # Timeline API integration tests
|
||||
StellaOps.TimelineIndexer.Tests/ # Indexer unit and integration tests
|
||||
```
|
||||
|
||||
## Data Flow
|
||||
|
||||
1. Events are produced by various Stella Ops services and carry HLC timestamps.
|
||||
2. TimelineIndexer (separate module) ingests and indexes these events into the event store.
|
||||
2. TimelineIndexer Worker (background service within this module) consumes events from the message bus, assigns HLC timestamps, and writes indexed events to the event store.
|
||||
3. Timeline WebService receives query requests from Platform, CLI, Web, or Replay.
|
||||
4. Timeline Core executes queries against the indexed event store, applying correlation, service, and time-range filters.
|
||||
5. Results are returned in HLC-sorted order, with optional critical path analysis computing latency stages between correlated events.
|
||||
|
||||
### Unified Audit Aggregator Flow
|
||||
|
||||
1. `UnifiedAuditEndpoints` receives `/api/v1/audit/*` requests from Web/CLI clients.
|
||||
2. `UnifiedAuditAggregationService` retrieves events from `IUnifiedAuditEventProvider`.
|
||||
3. `HttpUnifiedAuditEventProvider` queries module audit APIs (JobEngine, Policy, EvidenceLocker, Notify) and normalizes heterogeneous payloads into a unified event model.
|
||||
4. Aggregation computes stats, correlations, anomalies, and export state from the normalized event set.
|
||||
5. If a module source is unavailable or non-successful, Timeline logs the source failure and continues with partial data instead of failing the unified endpoint.
|
||||
|
||||
## Database Schema
|
||||
|
||||
Timeline reads from the event store managed by the Eventing infrastructure (PostgreSQL). Key columns queried:
|
||||
@@ -58,13 +83,26 @@ Timeline reads from the event store managed by the Eventing infrastructure (Post
|
||||
|
||||
## 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 |
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/api/v1/timeline/{correlationId}` | Query events by correlation ID (HLC-ordered). |
|
||||
| GET | `/api/v1/timeline/{correlationId}/critical-path` | Critical path analysis for a correlation. |
|
||||
| POST | `/api/v1/timeline/{correlationId}/replay` | Initiate deterministic replay for a correlation. |
|
||||
| GET | `/api/v1/timeline/replay/{replayId}` | Replay status lookup. |
|
||||
| POST | `/api/v1/timeline/replay/{replayId}/cancel` | Cancel replay operation. |
|
||||
| POST | `/api/v1/timeline/{correlationId}/export` | Initiate timeline export. |
|
||||
| GET | `/api/v1/timeline/export/{exportId}` | Export status lookup. |
|
||||
| GET | `/api/v1/timeline/export/{exportId}/download` | Download export bundle. |
|
||||
| GET | `/api/v1/audit/events` | Unified audit event list with filters and cursor paging. |
|
||||
| GET | `/api/v1/audit/events/{eventId}` | Unified audit event-by-id lookup. |
|
||||
| GET | `/api/v1/audit/stats` | Unified audit summary statistics. |
|
||||
| GET | `/api/v1/audit/timeline/search` | Unified audit timeline search. |
|
||||
| GET | `/api/v1/audit/correlations` | Correlation cluster list. |
|
||||
| GET | `/api/v1/audit/correlations/{correlationId}` | Correlation cluster details. |
|
||||
| GET | `/api/v1/audit/anomalies` | Unified anomaly alerts. |
|
||||
| POST | `/api/v1/audit/anomalies/{alertId}/acknowledge` | Acknowledge anomaly alert. |
|
||||
| POST | `/api/v1/audit/export` | Request unified audit export. |
|
||||
| GET | `/api/v1/audit/export/{exportId}` | Unified audit export status. |
|
||||
|
||||
## Security Considerations
|
||||
|
||||
@@ -73,12 +111,23 @@ Timeline reads from the event store managed by the Eventing infrastructure (Post
|
||||
- **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.
|
||||
- **Unified audit authorization**: `/api/v1/audit/*` read operations require `timeline:read`; acknowledge/export operations require `timeline:write`; tenant context is mandatory.
|
||||
|
||||
## Relationship to TimelineIndexer
|
||||
## TimelineIndexer (Event Ingestion and Indexing)
|
||||
|
||||
Timeline and TimelineIndexer are separate deployable services with distinct responsibilities:
|
||||
TimelineIndexer was consolidated into the Timeline module (Sprint 210, 2026-03-04). It provides the write/ingestion side of the CQRS pattern while Timeline provides the read/query side. Both share the same schema domain and live under `src/Timeline/`.
|
||||
|
||||
- **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.
|
||||
### TimelineIndexer Responsibilities
|
||||
|
||||
This separation allows independent scaling of ingestion and query workloads.
|
||||
- **Event ingestion**: Consumes events from NATS/Redis message bus via configurable subscribers.
|
||||
- **HLC timestamping**: Assigns Hybrid Logical Clock timestamps to establish causal ordering.
|
||||
- **Event indexing**: Writes indexed events to PostgreSQL via EfCore (compiled model preserved for migration identity).
|
||||
- **Authorization audit**: Provides audit sink for authorization events.
|
||||
|
||||
### Deployable Services
|
||||
|
||||
- **TimelineIndexer WebService** (`StellaOps.TimelineIndexer.WebService`): HTTP API for direct event submission and query.
|
||||
- **TimelineIndexer Worker** (`StellaOps.TimelineIndexer.Worker`): Background service for continuous event ingestion. Separately deployable container for independent scaling.
|
||||
- **Timeline WebService** (`StellaOps.Timeline.WebService`): Read-only query, analysis, export, and replay API.
|
||||
|
||||
This separation allows independent scaling of ingestion and query workloads while sharing domain libraries under a single module boundary.
|
||||
|
||||
Reference in New Issue
Block a user