Configuration

This document outlines the configuration options for the MSR (Multi-Session Replay) module. These settings allow you to customize the behavior of the frontend modlet, backend server, and integration components.

Frontend Modlet Configuration

Environment Variables

Configure the MSR modlet through environment variables in your web-base project's .env file:

Environment Variable	Example Value	Description
MSR_URL	http://msr.127.0.0.1.nip.io	Base URL for MSR backend API endpoints
IAMS_AAS_URL	http://iams-aas.127.0.0.1.nip.io	Authorization service endpoint for MSR authentication

Component Configuration

MultiSessionReplay Component Props

The main replay component accepts the following configuration props:

interface MultiSessionReplayProps {
	lobbyTitle: string; // Title shown in lobby screen
	lobbyDescription: string; // Description text in lobby
	lobbyButtonText: string; // Text for lobby start button
	playbackWindowMinutes?: number; // Default playback window (default: 120)
		startBufferMinutes?: number; // Buffer earliest selectable time (default: playbackWindowMinutes)
		endBufferMinutes?: number; // Buffer latest selectable time (default: playbackWindowMinutes)
		performanceOptions?: MsrPerformanceOptions; // Performance tuning options
		blurTargetElement?: HTMLElement; // Element to blur during modals
		errorHandling?: ErrorHandlingConfig; // Custom error handling configuration
	}

Prop	Type	Required	Default	Description
lobbyTitle	string	Yes	-	Title displayed in the lobby screen when component first loads
lobbyDescription	string	Yes	-	Description text shown in the lobby to explain the replay feature
lobbyButtonText	string	Yes	-	Text for the button that starts the replay session selection
playbackWindowMinutes	number	No	120	Duration in minutes for each replay session. Determines how long from the selected start time the replay will cover
startBufferMinutes	number	No	playbackWindowMinutes	Safety buffer (minutes) applied to earliest selectable time. Prevents selecting times too close to data cleanup boundaries
endBufferMinutes	number	No	playbackWindowMinutes	Safety buffer (minutes) applied to latest selectable time. Prevents selecting times where CDC data may not yet exist
performanceOptions	MsrPerformanceOptions	No	See Performance Options	Fine-tune replay performance for specific hardware and use cases
blurTargetElement	HTMLElement	No	undefined	Optional DOM element to apply blur effect when MSR dialogs are open (useful for backdrop effects)
errorHandling	ErrorHandlingConfig	No	Default Sonner toast config	Custom error handling configuration. Allows overriding default error display behavior with custom handlers

Playback Range Buffers

New in v1.3.0: MSR includes configurable safety buffers to prevent users from selecting times too close to data boundaries:

• startBufferMinutes: Applies a buffer to the earliest selectable time to prevent selection too close to data cleanup boundaries
• endBufferMinutes: Applies a buffer to the latest selectable time to prevent selection where CDC data may not yet exist
• Both buffers default to the playbackWindowMinutes value for consistent safety margins
• Buffers are applied to the date/time picker UI components automatically

Performance Options Configuration

Fine-tune replay performance for your specific use case:

interface MsrPerformanceOptions {
	pollWindowMs?: number; // Time window for fetching CDC data (default: 3000)
	frameRate?: number; // Rendering rate in FPS (default: 30)
	maxBufferSize?: number; // Max buffered changes (default: 1,000,000)
	minPollingInterval?: number; // Min interval between requests (default: 100)
}

Configuration Examples

Basic Component Usage

src/routes/my-replay/+page.svelte

<script>
  import { MultiSessionReplay } from '$lib/aoh/msr/components/MultiSessionReplay';
</script>

<MultiSessionReplay
  lobbyTitle="System Replay"
  lobbyDescription="Review historical system state changes"
  lobbyButtonText="Start Replay Session"
  playbackWindowMinutes={480}
/>

Performance Optimized Configuration

src/routes/my-replay/+page.svelte

<script>
  import { MultiSessionReplay } from '$lib/aoh/msr/components/MultiSessionReplay';

  const highPerformanceOptions = {
    pollWindowMs: 1000,      // Faster polling for high-frequency data
    frameRate: 60,           // Smooth animation
    maxBufferSize: 2000000,  // Larger buffer for bursty data
    minPollingInterval: 50   // Reduced minimum interval
  };
</script>

<MultiSessionReplay
  lobbyTitle="Real-time Analysis"
  lobbyDescription="High-frequency data replay"
  lobbyButtonText="Begin Analysis"
  playbackWindowMinutes={60}
  performanceOptions={highPerformanceOptions}
/>

Low Resource Configuration

src/routes/my-replay/+page.svelte

<script>
  const lowResourceOptions = {
    pollWindowMs: 5000,      // Slower polling to reduce load
    frameRate: 15,           // Lower frame rate
    maxBufferSize: 500000,   // Smaller buffer
    minPollingInterval: 200  // Higher minimum interval
  };
</script>

<MultiSessionReplay
  lobbyTitle="Lightweight Replay"
  lobbyDescription="Resource-efficient replay mode"
  lobbyButtonText="Start Session"
  playbackWindowMinutes={120}
  performanceOptions={lowResourceOptions}
/>

Buffered Time Range Configuration

src/routes/my-replay/+page.svelte

<MultiSessionReplay
  lobbyTitle="System Analysis"
  lobbyDescription="Historical data replay with safety buffers"
  lobbyButtonText="Start Analysis"
  playbackWindowMinutes={240}
  startBufferMinutes={60}  // 1-hour buffer from earliest time
  endBufferMinutes={30}    // 30-minute buffer from latest time
/>

Error Handling Configuration

The MSR includes a comprehensive error handling system with customizable behavior:

interface ErrorHandlingConfig {
	/**
	 * Custom error handler function
	 * If not provided, uses the default Sonner toast implementation
	 */
	onError?: ErrorHandler;

	/**
	 * Global error handling options
	 */
	defaultOptions?: ErrorHandlerOptions;
}

interface ErrorHandlerOptions {
	showToast?: boolean; // Show error toast notification (default: true)
	logError?: boolean; // Log error to console (default: true)
	throwError?: boolean; // Re-throw error for upstream handling (default: false)
}

By default, MSR uses Sonner toast notifications for user-friendly error messages with correlation IDs for support. You can customize this behavior:

Custom error handling example

<script>
  import { MultiSessionReplay } from '$lib/aoh/msr/components/MultiSessionReplay';

  const customErrorHandling = {
    onError: async (error, context, options) => {
      // Custom error handling logic
      log.error({ error.code, error.message }, 'MSR Error');
      // Send to custom error tracking service
      trackError(error.correlationId, context);
    },
    defaultOptions: {
      showToast: false,  // Disable default toasts
      logError: true,
      throwError: false
    }
  };
</script>

<MultiSessionReplay
  lobbyTitle="System Replay"
  lobbyDescription="Review historical changes"
  lobbyButtonText="Start Session"
  errorHandling={customErrorHandling}
/>

Filtering Configuration

The MSR component supports filtering to exclude stale or irrelevant data.

• stateFilterConfig (MsrStateFilterConfig): Applies when loading initial state at the selected timestamp
• playbackFilterConfig (MsrPlaybackFilterConfig): Applies while polling for events during playback

Both configurations have the shape:

interface MsrStateFilterConfig {
  tables: string[];
  getMinTimestamp: (context: {
    targetTimestamp: Date;
    playbackStartTime: Date;
    playbackEndTime: Date;
  }) => Date;
}

interface MsrPlaybackFilterConfig {
  tables: string[];
  getMinTimestamp: (context: {
    targetTimestamp: Date;
    playbackStartTime: Date;
    playbackEndTime: Date;
    eventWindowStart: Date;
    eventWindowEnd: Date;
  }) => Date;
}

Examples (dayjs):

Filter out old state (7 days) and logs (1 day)

<script>
  import dayjs from 'dayjs';
</script>

<MultiSessionReplay
  lobbyTitle="Replay"
  lobbyDescription="Historical system replay"
  lobbyButtonText="Start"
  stateFilterConfig={{
    tables: ['patients', 'medications'],
    getMinTimestamp: ({ targetTimestamp }) => dayjs(targetTimestamp).subtract(7, 'day').toDate()
  }}
  playbackFilterConfig={{
    tables: ['audit_logs', 'activity_logs'],
    getMinTimestamp: ({ targetTimestamp }) => dayjs(targetTimestamp).subtract(1, 'day').toDate()
  }}
/>

Notes:

• Filters are optional; omit to fetch all data
• One minTimestamp applies to all specified tables in a given config
• Callbacks re-run when the user changes the target time
• State filters reduce initial load size; playback filters reduce polling payloads

Backend Server Environment Variables

Environment Variable

The following environment variables are available for configuring the MSR backend server.

Environment Variable	Example Value	Description
LOG_LEVEL	info	Logging level: debug, info, warn, error
APP_PORT	8080	Port for the backend server to listen on
DATABASE_USER	msr_user	Database username
DATABASE_PASSWORD	secret	Database password
DATABASE_HOST	localhost	Database host address
DATABASE_PORT	5432	Database port number
DATABASE_NAME	msr_db	Name of the database
DATABASE_SCHEMA	public	Database schema to use
DATABASE_SSL_MODE	disable	Database connection ssl mode: disable, require, verify-ca, verify-full
DATABASE_MAX_CONNS	10	Maximum number of open database connections
DATABASE_MAX_IDLE_CONNS	10	Maximum number of idle database connections
DATABASE_MAX_CONN_LIFETIME	10m	Maximum lifetime of a database connection (e.g., 10m, 1h)
IAMS_KEYCLOAK_URL	http://iams-keycloak.127.0.0.1.nip.io/realms/aoh	URL of the Keycloak realm for authentication
CLEANUP_SERVICE_ENABLED	true	Enable/disable automatic CDC cleanup service (set to false in development)

Configuration Table

The following configuration is stored in the database for the MSR backend server. These values can be modified at runtime without requiring a service restart. Changes take effect on the next scheduled maintenance cycle or immediately for session limits.

Core Configuration Settings

Config key	Example value	Config type	Description
MAX_PLAYBACK_RANGE	7	INTEGER	Maximum number of previous days available for replay. Determines snapshot cutoff point and affects available date range in UI.
MAX_ACTIVE_SESSIONS	5	INTEGER	Maximum number of concurrent active replay sessions. If limit is reached, new sessions receive an error prompting them to close existing sessions.
DATA_RETENTION_CRON_EXPRESSION	0 3 * * *	STRING	Cron expression for complete maintenance cycle: refreshes snapshots at cutoff point and removes old CDC events. Default: daily at 3am.
EARLIEST_VALID_TIMESTAMP	1900-01-01T00:00:00Z	STRING	Absolute earliest timestamp for replay data (ISO 8601 format). Set to deployment date for new systems to prevent empty replays. Default effectively disabled.

Performance Tuning Configuration

Config key	Example value	Config type	Description
QUERY_WORK_MEM_MB	256	INTEGER	Memory allocation in MB for hash joins and sorting in replay queries. Higher values improve performance for large datasets. Default: 256MB.
COLUMNSTORE_COMPRESSION_AGE_DAYS	1	INTEGER	Age in days before cdc_event chunks compress to columnstore format. Recent data stays uncompressed for fast inserts. Default: 1 day.
CAGG_REFRESH_INTERVAL_HOURS	1	INTEGER	How often continuous aggregate refreshes (in hours). More frequent refreshes will yield faster query times at the expense storage space. Default: 1 hour.
CAGG_REFRESH_LAG_DAYS	1	INTEGER	How far behind current time the CAGG refreshes (in days). Prevents refreshing actively-inserting chunks. Default: 1 day.

Configuration Relationships

Several configuration values are interdependent:

• CAGG retention is automatically calculated as MAX_PLAYBACK_RANGE + 1 day
• CAGG columnstore compression is calculated as CAGG retention + 1 day
• All cutoff calculations are dynamic and based on current MAX_PLAYBACK_RANGE value
• EARLIEST_VALID_TIMESTAMP serves as an absolute minimum, even if MAX_PLAYBACK_RANGE would allow earlier dates