Skip to Content
UptimeBeacon 1.0 is released 🎉
Configuration

Configuration

This guide covers all configuration options available in Sentinel Guard, from basic setup to advanced customization.

Core Configuration

SentinelGuardConfig

The main configuration object passed to the SentinelGuard constructor:

interface SentinelGuardConfig {
	apiKey: string;
	baseUrl: string;
	monitorApiKey: string;
	timeout?: number;
	retryConfig?: RetryConfig;
}

Required Configuration

apiKey

  • Type: string
  • Description: Your UptimeBeacon.cloud API key
  • Example: "ub_api_1234567890abcdef"

baseUrl

  • Type: string
  • Description: The base URL for the UptimeBeacon API
  • Example: "https://api.uptimebeacon.cloud"

monitorApiKey

  • Type: string
  • Description: Monitor-specific API key for your monitoring endpoint
  • Example: "mon_1234567890abcdef"

Optional Configuration

timeout

  • Type: number
  • Default: 10000
  • Description: Request timeout in milliseconds
  • Range: 1000 to 60000
const sentinel = new SentinelGuard({
	apiKey: process.env.SENTINEL_API_KEY!,
	baseUrl: process.env.SENTINEL_API_URL!,
	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
	timeout: 15000, // 15 seconds
});

Retry Configuration

Configure automatic retry behavior for failed requests:

interface RetryConfig {
	maxRetries: number;
	baseDelay: number;
	backoffMultiplier: number;
}

Retry Options

maxRetries

  • Type: number
  • Default: 3
  • Description: Maximum number of retry attempts
  • Range: 0 to 10

baseDelay

  • Type: number
  • Default: 1000
  • Description: Base delay between retries in milliseconds
  • Range: 100 to 5000

backoffMultiplier

  • Type: number
  • Default: 2
  • Description: Exponential backoff multiplier
  • Range: 1 to 5
const sentinel = new SentinelGuard({
	apiKey: process.env.SENTINEL_API_KEY!,
	baseUrl: process.env.SENTINEL_API_URL!,
	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
	retryConfig: {
		maxRetries: 5,
		baseDelay: 2000,
		backoffMultiplier: 2.5,
	},
});

Heartbeat Configuration

Configure automatic heartbeat monitoring:

interface HeartbeatConfig {
	interval: number;
	maxConsecutiveErrors?: number;
}

Heartbeat Options

interval

  • Type: number
  • Description: Heartbeat interval in milliseconds
  • Minimum: 5000 (5 seconds)
  • Maximum: 600000 (10 minutes)
  • Recommended: 30000 to 120000 (30 seconds to 2 minutes)

maxConsecutiveErrors

  • Type: number
  • Default: 5
  • Description: Maximum consecutive errors before stopping monitoring
  • Range: 1 to 20
sentinel.startMonitoring({
	interval: 45000, // 45 seconds
	maxConsecutiveErrors: 3,
});

Environment Variables

Configure Sentinel Guard using environment variables:

# Required
SENTINEL_API_KEY=your-api-key-here
SENTINEL_API_URL=https://api.uptimebeacon.cloud
SENTINEL_MONITOR_API_KEY=your-monitor-api-key-here

# Optional
SENTINEL_TIMEOUT=10000
SENTINEL_MAX_RETRIES=3
SENTINEL_BASE_DELAY=1000
SENTINEL_BACKOFF_MULTIPLIER=2

Load environment variables in your application:

import { SentinelGuard } from "@uptimebeacon/sentinel-guard";
 
const sentinel = new SentinelGuard({
	apiKey: process.env.SENTINEL_API_KEY!,
	baseUrl: process.env.SENTINEL_API_URL!,
	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
	timeout: Number(process.env.SENTINEL_TIMEOUT) || 10000,
	retryConfig: {
		maxRetries: Number(process.env.SENTINEL_MAX_RETRIES) || 3,
		baseDelay: Number(process.env.SENTINEL_BASE_DELAY) || 1000,
		backoffMultiplier: Number(process.env.SENTINEL_BACKOFF_MULTIPLIER) || 2,
	},
});

Database Configuration

Configure database clients for performance monitoring:

Prisma Configuration

import { PrismaClient } from "@prisma/client";
 
const prisma = new PrismaClient();
sentinel.setPrismaClient(prisma);

Requirements:

  • Prisma client must have $queryRaw method
  • Connection must be established before setting

Redis Configuration

import { createClient } from "redis";
 
const redis = createClient({
	url: process.env.REDIS_URL,
});
await redis.connect();
sentinel.setRedisClient(redis);

Requirements:

  • Redis client must have ping method
  • Connection must be established before setting

Advanced Configuration

Custom Metadata

Configure default metadata for all heartbeats:

class MonitoringService {
	private sentinel: SentinelGuard;
	private defaultMetadata: Record<string, unknown>;
 
	constructor() {
		this.sentinel = new SentinelGuard({
			apiKey: process.env.SENTINEL_API_KEY!,
			baseUrl: process.env.SENTINEL_API_URL!,
			monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
		});
 
		this.defaultMetadata = {
			service: "my-application",
			version: process.env.APP_VERSION || "1.0.0",
			environment: process.env.NODE_ENV || "development",
		};
	}
 
	async sendCustomHeartbeat(additionalMetadata?: Record<string, unknown>) {
		return this.sentinel.sendHeartbeat({
			status: "ONLINE",
			metadata: {
				...this.defaultMetadata,
				...additionalMetadata,
			},
		});
	}
}

Configuration Validation

Validate configuration before use:

function validateConfig(config: SentinelGuardConfig): void {
	if (!config.apiKey) {
		throw new Error("API key is required");
	}
 
	if (!config.baseUrl) {
		throw new Error("Base URL is required");
	}
 
	if (!config.monitorApiKey) {
		throw new Error("Monitor API key is required");
	}
 
	if (config.timeout && (config.timeout < 1000 || config.timeout > 60000)) {
		throw new Error("Timeout must be between 1000 and 60000 milliseconds");
	}
}
 
const config = {
	apiKey: process.env.SENTINEL_API_KEY!,
	baseUrl: process.env.SENTINEL_API_URL!,
	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
	timeout: 15000,
};
 
validateConfig(config);
const sentinel = new SentinelGuard(config);

Configuration Best Practices

Security

  1. Never hardcode credentials

    // BAD
const sentinel = new SentinelGuard({
	apiKey: "ub_api_1234567890abcdef",
	baseUrl: "https://api.uptimebeacon.cloud",
	monitorApiKey: "mon_1234567890abcdef",
});
 
// GOOD
const sentinel = new SentinelGuard({
	apiKey: process.env.SENTINEL_API_KEY!,
	baseUrl: process.env.SENTINEL_API_URL!,
	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
});

  2. Use environment-specific configurations

    const config = {
	apiKey: process.env.SENTINEL_API_KEY!,
	baseUrl: process.env.SENTINEL_API_URL!,
	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
	timeout: process.env.NODE_ENV === "production" ? 15000 : 5000,
};

Performance

  1. Optimize heartbeat intervals

    • Production: 30-120 seconds
    • Development: 10-30 seconds
    • Testing: 5-10 seconds

  2. Configure appropriate timeouts

    • Fast networks: 5-10 seconds
    • Slow networks: 15-30 seconds
    • Mobile networks: 30-60 seconds

  3. Set reasonable retry limits

    • Production: 3-5 retries
    • Development: 1-3 retries
    • Testing: 0-1 retries

Monitoring

  1. Use appropriate error thresholds

    const errorThreshold = process.env.NODE_ENV === "production" ? 5 : 3;
 
sentinel.startMonitoring({
	interval: 30000,
	maxConsecutiveErrors: errorThreshold,
});

  2. Monitor configuration changes

    console.log("Monitoring configuration:", {
	interval: config.interval,
	maxErrors: config.maxConsecutiveErrors,
	timeout: sentinel.timeout,
});

Configuration Examples

Production Configuration

const sentinel = new SentinelGuard({
	apiKey: process.env.SENTINEL_API_KEY!,
	baseUrl: process.env.SENTINEL_API_URL!,
	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
	timeout: 15000,
	retryConfig: {
		maxRetries: 5,
		baseDelay: 2000,
		backoffMultiplier: 2,
	},
});
 
sentinel.startMonitoring({
	interval: 60000, // 1 minute
	maxConsecutiveErrors: 5,
});

Development Configuration

const sentinel = new SentinelGuard({
	apiKey: process.env.SENTINEL_API_KEY!,
	baseUrl: process.env.SENTINEL_API_URL!,
	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
	timeout: 5000,
	retryConfig: {
		maxRetries: 2,
		baseDelay: 1000,
		backoffMultiplier: 1.5,
	},
});
 
sentinel.startMonitoring({
	interval: 15000, // 15 seconds
	maxConsecutiveErrors: 3,
});

High-Frequency Monitoring

const sentinel = new SentinelGuard({
	apiKey: process.env.SENTINEL_API_KEY!,
	baseUrl: process.env.SENTINEL_API_URL!,
	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
	timeout: 5000,
	retryConfig: {
		maxRetries: 3,
		baseDelay: 500,
		backoffMultiplier: 1.5,
	},
});
 
sentinel.startMonitoring({
	interval: 10000, // 10 seconds
	maxConsecutiveErrors: 2,
});
ExamplesAPI Reference