172 lines
6.5 KiB
Markdown
172 lines
6.5 KiB
Markdown
# Timeline UI Component
|
|
|
|
> **Module:** Eventing / Timeline
|
|
> **Status:** Implemented
|
|
> **Last Updated:** 2026-01-07
|
|
|
|
## Overview
|
|
|
|
The Timeline UI provides a visual representation of HLC-ordered events across StellaOps services. It enables operators to trace the causal flow of operations, identify bottlenecks, and investigate specific events with full evidence links.
|
|
|
|
## Features
|
|
|
|
### Causal Lanes Visualization
|
|
|
|
Events are displayed in swimlanes organized by service:
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ HLC Timeline Axis │
|
|
│ |-------|-------|-------|-------|-------|-------|-------|-------> │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ Scheduler [E]─────────[X]───────────────[C] │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ AirGap [I]──────────[M] │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ Attestor [A]──────────[V] │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ Policy [G] │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
Legend:
|
|
- **[E]** Enqueue - Job queued for processing
|
|
- **[X]** Execute - Job execution started
|
|
- **[C]** Complete - Job completed
|
|
- **[I]** Import - Data imported (e.g., SBOM, advisory)
|
|
- **[M]** Merge - Data merged
|
|
- **[A]** Attest - Attestation created
|
|
- **[V]** Verify - Attestation verified
|
|
- **[G]** Gate - Policy gate evaluated
|
|
|
|
### Critical Path Analysis
|
|
|
|
The critical path view shows the longest sequence of dependent operations:
|
|
|
|
- Color-coded by severity (green/yellow/red)
|
|
- Bottleneck stage highlighted
|
|
- Percentage of total duration shown
|
|
- Clickable stages for drill-down
|
|
|
|
### Event Detail Panel
|
|
|
|
Selected events display:
|
|
- Event ID and metadata
|
|
- HLC timestamp and wall-clock time
|
|
- Service and event kind
|
|
- JSON payload viewer
|
|
- Engine version information
|
|
- Evidence links (SBOM, VEX, Policy, Attestation)
|
|
|
|
### Filtering
|
|
|
|
Events can be filtered by:
|
|
- **Services**: Scheduler, AirGap, Attestor, Policy, Scanner, etc.
|
|
- **Event Kinds**: ENQUEUE, EXECUTE, COMPLETE, IMPORT, ATTEST, etc.
|
|
- **HLC Range**: From/To timestamps
|
|
|
|
Filter state is persisted in URL query parameters.
|
|
|
|
### Export
|
|
|
|
Timeline data can be exported as:
|
|
- **NDJSON**: Newline-delimited JSON (streaming-friendly)
|
|
- **JSON**: Standard JSON array
|
|
- **DSSE-signed**: Cryptographically signed bundles for auditing
|
|
|
|
## Usage
|
|
|
|
### Accessing the Timeline
|
|
|
|
Navigate to `/timeline/{correlationId}` where `correlationId` is the unique identifier for a scan, job, or workflow.
|
|
|
|
Example:
|
|
```
|
|
/timeline/scan-abc123-def456
|
|
```
|
|
|
|
### Keyboard Navigation
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| Tab | Navigate between events |
|
|
| Enter/Space | Select focused event |
|
|
| Escape | Clear selection |
|
|
| Arrow keys | Scroll within panel |
|
|
|
|
### URL Parameters
|
|
|
|
| Parameter | Description | Example |
|
|
|-----------|-------------|---------|
|
|
| `services` | Comma-separated service filter | `?services=Scheduler,AirGap` |
|
|
| `kinds` | Comma-separated kind filter | `?kinds=EXECUTE,COMPLETE` |
|
|
| `fromHlc` | Start of HLC range | `?fromHlc=1704067200000:0:node1` |
|
|
| `toHlc` | End of HLC range | `?toHlc=1704153600000:0:node1` |
|
|
|
|
## Component Architecture
|
|
|
|
```
|
|
timeline/
|
|
├── components/
|
|
│ ├── causal-lanes/ # Swimlane visualization
|
|
│ ├── critical-path/ # Bottleneck bar chart
|
|
│ ├── event-detail-panel/ # Selected event details
|
|
│ ├── evidence-links/ # Links to SBOM/VEX/Policy
|
|
│ ├── export-button/ # Export dropdown
|
|
│ └── timeline-filter/ # Service/kind filters
|
|
├── models/
|
|
│ └── timeline.models.ts # TypeScript interfaces
|
|
├── pages/
|
|
│ └── timeline-page/ # Main page component
|
|
├── services/
|
|
│ └── timeline.service.ts # API client
|
|
└── timeline.routes.ts # Lazy-loaded routes
|
|
```
|
|
|
|
## API Integration
|
|
|
|
The Timeline UI integrates with the Timeline API:
|
|
|
|
| Endpoint | Description |
|
|
|----------|-------------|
|
|
| `GET /api/v1/timeline/{correlationId}` | Fetch events |
|
|
| `GET /api/v1/timeline/{correlationId}/critical-path` | Fetch critical path |
|
|
| `POST /api/v1/timeline/{correlationId}/export` | Initiate export |
|
|
| `GET /api/v1/timeline/export/{exportId}` | Check export status |
|
|
| `GET /api/v1/timeline/export/{exportId}/download` | Download bundle |
|
|
|
|
## Accessibility
|
|
|
|
The Timeline UI follows WCAG 2.1 AA guidelines:
|
|
|
|
- **Keyboard Navigation**: All interactive elements are focusable
|
|
- **Screen Readers**: ARIA labels on all regions and controls
|
|
- **Color Contrast**: 4.5:1 minimum contrast ratio
|
|
- **Focus Indicators**: Visible focus rings on all controls
|
|
- **Motion**: Respects `prefers-reduced-motion`
|
|
|
|
## Performance
|
|
|
|
- **Virtual Scrolling**: Handles 10K+ events efficiently
|
|
- **Lazy Loading**: Events loaded on-demand as user scrolls
|
|
- **Caching**: Recent queries cached to reduce API calls
|
|
- **Debouncing**: Filter changes debounced to avoid excessive requests
|
|
|
|
## Screenshots
|
|
|
|
### Timeline View
|
|
|
|
|
|
### Critical Path Analysis
|
|
|
|
|
|
### Event Detail Panel
|
|
|
|
|
|
## Related Documentation
|
|
|
|
- [Timeline API Reference](../../api/timeline-api.md)
|
|
- [HLC Clock Specification](../hlc/architecture.md)
|
|
- [Eventing SDK](../eventing/architecture.md)
|
|
- [Evidence Model](../../schemas/evidence.md)
|