timeline Package

Overview#

Package timeline provides comprehensive incident timeline management and event sourcing for the incident management platform.

The timeline package implements the core event sourcing system that maintains a chronological record of all incident activities, state changes, and interactions. It serves as the authoritative source of truth for incident history and enables real-time updates, audit trails, and state reconstruction for the entire incident management system.

Key Features:

• Event sourcing with append-only timeline storage
• CloudEvents v1.0 compliant event structures for interoperability
• State machine integration for consistent incident state transitions
• Real-time event broadcasting to connected clients
• Automatic correlation and SLA tracking integration
• Comprehensive audit trails for compliance and forensics
• Materialized view maintenance for query performance
• Integration with external ITSM systems through connectors

Architecture:

The timeline system follows an event sourcing pattern with materialized views:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ Timeline Events │───►│ State Machine    │───►│ Incident Views  │
│ (Append-Only)   │    │ (Validation)     │    │ (Materialized)  │
└─────────────────┘    └──────────────────┘    └─────────────────┘

      │                        │                        │

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ Real-time       │    │ SLA Tracking     │    │ Correlation     │
│ Broadcasting    │    │ (Metrics)        │    │ (Deduplication) │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Event Types:

• declare: New incident creation with initial metadata
• ack: Incident acknowledgment by responder
• mitigate: Mitigation action taken to reduce impact
• resolve: Incident resolution with root cause
• close: Incident closure after verification
• note: Commentary and status updates
• role_assign: Role assignment (incident commander, ops lead, etc.)
• state_change: Generic status transitions

Example usage:

// Create timeline service
timelineService := timeline.New(db)
timelineService.SetBroadcaster(realtimeBroadcaster)

// Declare new incident
event := &models.TimelineEvent{
	IncidentID:  "INC-123",
	EventType:   models.EventTypeDeclare,
	Actor:       "user@example.com",
	Title:       "Database Connection Issues",
	Content:     "Users reporting connection timeouts",
	EventTime:   time.Now(),
	Source:      "web-ui",
}

ce := &models.CloudEvent{
	Type:    "com.systmms.incident.declare",
	Source:  "web-ui",
	Subject: "INC-123",
}

err := timelineService.AppendEvent(event, ce)
if err != nil {
	log.Fatal(err)
}

// Retrieve incident timeline
events, err := timelineService.GetTimeline("INC-123", 50)
if err != nil {
	log.Fatal(err)
}

CloudEvents Integration: All timeline events are stored as CloudEvents v1.0 compliant structures, enabling integration with external event systems, message brokers, and cloud-native event processing pipelines.

State Management: The service integrates with a state machine to validate incident state transitions, ensuring business rules are enforced and preventing invalid state changes that could compromise incident data integrity.

Real-time Updates: Timeline events are automatically broadcast to connected clients through the real-time broadcasting system, providing immediate visibility of incident changes without polling or refresh requirements.

Import Path: github.com/systmms/incidents/internal/timeline

Types#

Broadcaster#

Broadcaster interface defines real-time event broadcasting capabilities.

This interface abstracts the real-time communication system, allowing the timeline service to broadcast events without coupling to specific transport protocols or client connection management. Implementations handle WebSocket, SSE, and other real-time delivery mechanisms.

Integration Pattern: The broadcaster is called after successful event persistence to ensure clients receive notifications only for committed changes. This prevents inconsistent state visibility during transaction rollbacks or system failures.

{<nil> 6816 type 0 [0x14000984b00] 0}

Correlator#

Correlator interface defines incident correlation and relationship detection.

This interface enables automatic detection of duplicate incidents, related events, and pattern recognition across the incident timeline. Correlation processing helps reduce noise, improve response efficiency, and provide better incident context.

The correlator operates asynchronously after event persistence to avoid blocking the main timeline operations while providing valuable analytical insights.

{<nil> 7794 type 0 [0x14000984d40] 0}

SLATracker#

SLATracker interface defines SLA monitoring and metrics collection.

This interface provides comprehensive SLA tracking capabilities, monitoring response times, resolution targets, and escalation thresholds. The tracker maintains metrics that drive alerting, reporting, and performance analysis.

SLA tracking operates alongside timeline events to provide real-time metrics and proactive notifications when service level agreements are at risk.

{<nil> 8571 type 0 [0x14000984f00] 0}

Service#

Service provides comprehensive timeline operations and event sourcing for incident management.

The Service acts as the central coordinator for all incident timeline activities, managing event persistence, state transitions, real-time broadcasting, and integration with supporting services like correlation and SLA tracking. It ensures data consistency through transactional operations and maintains the event sourcing paradigm.

Core Responsibilities:

• Append-only event storage with CloudEvents compliance
• State machine validation for incident transitions
• Materialized view maintenance for query performance
• Real-time event broadcasting to connected clients
• Integration with correlation and SLA tracking services
• Atomic operations with proper error handling and rollback

The service coordinates multiple subsystems while maintaining strict consistency guarantees and ensuring all side effects (broadcasting, metrics, correlation) are properly handled after successful event persistence.

{<nil> 5664 type 0 [0x14000984880] 0}

Methods#

New#

New creates a new timeline service with default configuration.

This constructor initializes the core timeline service with database access and a default state machine for incident transition validation. Additional services (broadcaster, correlator, SLA tracker) can be configured using the setter methods after creation.

The service is immediately ready for basic timeline operations after creation, though full functionality requires configuration of supporting services through the SetBroadcaster, SetCorrelator, and SetSLATracker methods.

Parameters:

• db: Database connection for event storage and materialized view maintenance

Returns a configured Service ready for timeline operations and integration with the broader incident management platform.

{<nil> <nil> New 0x14000986ca0 <nil>}

Generated automatically from Go source code. Last updated: 2025-08-25T07:51:05-04:00