Memory Management for XyPriss Clustering

XyPriss provides comprehensive memory management capabilities to help you control resource usage while maintaining performance, safety, and security in clustered environments.

Overview

The memory management system provides:

Automatic Memory Monitoring: Real-time tracking of system and worker memory usage
Intelligent Scaling: Memory-based auto-scaling to prevent resource exhaustion
Memory Leak Detection: Automatic detection and handling of memory leaks
Low Memory Mode: Optimizations for resource-constrained environments
Configurable Limits: Fine-grained control over memory usage

Configuration Options

Basic Memory Management

import { createServer } from "xypriss";

const app = createServer({
  cluster: {
    enabled: true,
    config: {
      workers: "auto", // Will be optimized based on available memory
      resources: {
        maxMemoryPerWorker: "512MB", // Limit each worker to 512MB

        memoryManagement: {
          enabled: true,
          maxTotalMemory: "4GB", // Total cluster memory limit
          memoryCheckInterval: 30000, // Check every 30 seconds
          memoryWarningThreshold: 80, // Warning at 80% usage
          memoryCriticalThreshold: 95, // Critical at 95% usage
          autoScaleOnMemory: true, // Auto scale down on high memory
          memoryLeakDetection: true, // Enable leak detection
          lowMemoryMode: false, // Start in normal mode
          memoryReservation: "1GB", // Reserve 1GB for system
        },
      },
    },
  },
});

Advanced Memory Configuration

const app = createServer({
  cluster: {
    enabled: true,
    config: {
      workers: 4,
      resources: {
        maxMemoryPerWorker: "256MB", // Conservative per-worker limit

        memoryManagement: {
          enabled: true,
          maxTotalMemory: "2GB", // Total limit for low-memory systems
          memoryCheckInterval: 15000, // More frequent checks
          memoryWarningThreshold: 70, // Earlier warnings
          memoryCriticalThreshold: 85, // Earlier critical threshold
          autoScaleOnMemory: true,
          memoryLeakDetection: true,
          garbageCollectionHint: true, // Send GC hints to workers
          lowMemoryMode: true, // Start in low memory mode
          memoryReservation: "512MB", // Less system reservation
          swapUsageLimit: 5, // Limit swap usage to 5%
        },

        performanceOptimization: {
          enabled: true,
          lowMemoryMode: true, // Enable low memory optimizations
          reducedLogging: true, // Reduce memory used by logs
          compactMetrics: true, // Use compact metrics storage
          lazyWorkerInit: true, // Initialize workers on-demand
          workerPooling: true, // Reuse worker processes
          memoryPooling: true, // Use memory pooling
          disableDebugFeatures: true, // Disable debug features
          minimalFootprint: true, // Minimize memory footprint
          efficientDataStructures: true, // Use efficient data structures
        },

        enforcement: {
          enabled: true,
          enforceHardLimits: false, // Don't kill workers immediately
          softLimitWarnings: true, // Log warnings for soft limits
          gracefulDegradation: true, // Degrade gracefully
          resourceThrottling: true, // Throttle instead of killing
          alertOnLimitReached: true, // Send alerts
        },
      },

      autoScaling: {
        enabled: true,
        minWorkers: 1,
        maxWorkers: 6,
        memoryBasedScaling: true, // Prioritize memory-based scaling
        aggressiveMemoryScaling: true, // More aggressive scaling
        scaleDownThreshold: {
          memory: 30, // Scale down if memory < 30%
        },
        scaleUpThreshold: {
          memory: 80, // Scale up if memory > 80%
        },
      },
    },
  },
});

Memory Management API

Monitoring Memory Usage

// Get memory recommendations
const recommendations = app.getMemoryRecommendations();
console.log("Memory recommendations:", recommendations.recommendations);
console.log("Suggested worker count:", recommendations.suggestedWorkerCount);

// Get optimal worker count for current memory
const optimalWorkers = app.getOptimalWorkerCountForMemory();
console.log("Optimal worker count:", optimalWorkers);

// Check cluster health including memory
const health = await app.getClusterHealth();
console.log("Cluster healthy:", health.healthy);
console.log("Memory details:", health.details);

Manual Memory Management

// Enable low memory mode manually
app.enableLowMemoryMode();

// Disable low memory mode
app.disableLowMemoryMode();

// Scale based on memory pressure
if (memoryUsage > 90) {
  await app.scaleDown(1);
}

// Get current cluster metrics including memory
const metrics = await app.getClusterMetrics();
console.log("Memory usage:", metrics.memoryUsage);

Event Handling

// Listen for memory events
app.on("memory_alert", (alert) => {
  console.log(`Memory Alert: ${alert.message}`);
  console.log(`Action: ${alert.action}`);

  if (alert.type === "critical") {
    // Handle critical memory situation
    console.log("Taking emergency action for critical memory usage");
  }
});

app.on("low_memory_mode", (data) => {
  if (data.enabled) {
    console.log("Cluster entered low memory mode");
    // Adjust application behavior for low memory
  } else {
    console.log("Cluster exited low memory mode");
    // Resume normal operation
  }
});

app.on("memory_throttling", (data) => {
  console.log("Memory throttling activated:", data.action);
  // Reduce application concurrency or processing
});

Memory Optimization Strategies

For Low Memory Environments (< 4GB RAM)

const lowMemoryConfig = {
  cluster: {
    enabled: true,
    config: {
      workers: 2, // Fewer workers
      resources: {
        maxMemoryPerWorker: "256MB",
        memoryManagement: {
          enabled: true,
          maxTotalMemory: "1.5GB",
          memoryWarningThreshold: 60,
          memoryCriticalThreshold: 75,
          lowMemoryMode: true,
          memoryReservation: "512MB",
        },
        performanceOptimization: {
          enabled: true,
          lowMemoryMode: true,
          reducedLogging: true,
          compactMetrics: true,
          minimalFootprint: true,
          disableDebugFeatures: true,
        },
      },
    },
  },
};

For High Memory Environments (> 16GB RAM)

const highMemoryConfig = {
  cluster: {
    enabled: true,
    config: {
      workers: "auto", // Let system optimize
      resources: {
        maxMemoryPerWorker: "2GB",
        memoryManagement: {
          enabled: true,
          maxTotalMemory: "12GB",
          memoryWarningThreshold: 85,
          memoryCriticalThreshold: 95,
          lowMemoryMode: false,
          memoryReservation: "2GB",
          garbageCollectionHint: true,
        },
        performanceOptimization: {
          enabled: true,
          lowMemoryMode: false,
          workerPooling: true,
          memoryPooling: true,
        },
      },
    },
  },
};

Memory Monitoring Dashboard

Create a Memory Status Endpoint

app.get("/cluster/memory", async (req, res) => {
  const recommendations = app.getMemoryRecommendations();
  const optimalWorkers = app.getOptimalWorkerCountForMemory();
  const metrics = await app.getClusterMetrics();
  const health = await app.getClusterHealth();

  res.xJson({
    memory: {
      recommendations: recommendations.recommendations,
      suggestedWorkerCount: recommendations.suggestedWorkerCount,
      optimalWorkerCount: optimalWorkers,
      canEnableLowMemoryMode: recommendations.canEnableLowMemoryMode,
      currentUsage: metrics.memoryUsage,
      healthy: health.healthy,
      workers: app.getAllWorkers().map((w) => ({
        id: w.id,
        status: w.status,
        health: w.health.status,
        // Memory stats would be added here
      })),
    },
    timestamp: new Date().toISOString(),
  });
});

Best Practices

1. Start Conservative

// Begin with conservative settings and adjust based on monitoring
const conservativeConfig = {
  maxMemoryPerWorker: "256MB", // Start small
  memoryWarningThreshold: 70, // Early warnings
  memoryCriticalThreshold: 85, // Early critical alerts
};

2. Monitor and Adjust

// Regularly check memory recommendations
setInterval(async () => {
  const recommendations = app.getMemoryRecommendations();
  if (recommendations.recommendations.length > 0) {
    console.log("Memory recommendations:", recommendations.recommendations);
  }
}, 300000); // Every 5 minutes

3. Handle Memory Events

// Always handle memory events gracefully
app.on("memory_alert", async (alert) => {
  switch (alert.type) {
    case "warning":
      // Log and monitor
      logger.warn("Memory usage high", alert);
      break;
    case "critical":
      // Take immediate action
      await app.scaleDown(1);
      break;
    case "leak_detected":
      // Restart affected worker
      logger.error("Memory leak detected", alert);
      break;
  }
});

4. Environment-Specific Configuration

// Adjust configuration based on environment
const memoryConfig =
  process.env.NODE_ENV === "production"
    ? productionMemoryConfig
    : developmentMemoryConfig;

Troubleshooting

High Memory Usage

Check maxMemoryPerWorker setting
Enable memoryLeakDetection
Reduce workers count
Enable lowMemoryMode
Increase memoryCheckInterval frequency

Frequent Worker Restarts

Increase memoryWarningThreshold
Set enforceHardLimits: false
Enable gracefulDegradation
Check for memory leaks in application code

Poor Performance

Disable lowMemoryMode if memory is available
Increase maxMemoryPerWorker
Reduce memoryCheckInterval
Enable workerPooling and memoryPooling

The memory management system provides comprehensive control over resource usage while maintaining the performance, safety, and security of your clustered XyPriss applications.

Getting Started with XyPriss multi-server