Documentation•Reference

HazelJS Predictive Scaling Package

npm downloads

@hazeljs/​predictive-scaling forecasts traffic and raises Kubernetes HPA minReplicas before the spike — exponential smoothing, seasonal patterns, event boosts, and an optional Prometheus feed.

Use @hazeljs/​self-healing for reactive recovery (hpa-boost after latency degrades). This package is proactive.

Quick Reference

  • Purpose: Predict load ~30 minutes ahead and adjust HPA so pods exist before traffic arrives.
  • When to use: Kubernetes workloads with HPA, known launch events (black-friday), or Prometheus metrics you already scrape.
  • Key concepts: @PredictiveScaling, @ScalePredict, @ScaleOnEvent, createPredictiveScaler, attachPrometheusCollector, createOperationsStack.
  • Dependencies: @hazeljs/​core. Optional: @hazeljs/​self-healing (shared K8s scaling client), @hazeljs/​ai (LLM forecast hook).
  • Common patterns: Decorate the module → scaler.recordMetric('requests', n) or Prometheus poll → scaler.start() → triggerEvent('product-launch').
  • Common mistakes: Scaling without a confidence gate (cost blow-ups); forgetting costOptimization so scale-down is instant; using this instead of circuit breakers for failing dependencies.

Architecture

graph TD
  M["Metrics<br/>in-process / Prometheus"] --> F["Forecast engine<br/>smoothing + seasonality"]
  E["Business events"] --> F
  F --> H["HPA minReplicas"]
  S["@hazeljs/self-healing"] --> H
  
  style M fill:#3b82f6,stroke:#60a5fa,stroke-width:2px,color:#fff
  style F fill:#6366f1,stroke:#818cf8,stroke-width:2px,color:#fff
  style E fill:#f59e0b,stroke:#fbbf24,stroke-width:2px,color:#fff
  style H fill:#10b981,stroke:#34d399,stroke-width:2px,color:#fff
  style S fill:#ec4899,stroke:#f472b6,stroke-width:2px,color:#fff

Installation

npm install @hazeljs/​predictive-scaling @hazeljs/​core

Optional:

npm install @hazeljs/​self-healing @hazeljs/​ai

Quick Start

import {
  PredictiveScaling,
  ScalePredict,
  ScaleOnEvent,
  adaptSelfHealingScalingClient,
} from '@hazeljs/​predictive-scaling';
import { InMemoryKubernetesScalingClient } from '@hazeljs/​self-healing';

@PredictiveScaling({
  model: 'time-series-forecast',
  metrics: ['requests', 'latency'],
  horizon: '30m',
  confidence: 0.85,
  costOptimization: true,
  hpa: {
    name: 'video-hpa',
    namespace: 'prod',
    client: adaptSelfHealingScalingClient(new InMemoryKubernetesScalingClient()),
    maxReplicas: 100,
  },
})
@ScaleOnEvent({
  events: ['product-launch', 'black-friday'],
  maxScale: 100,
  scaleFactor: 2,
})
export class AppModule {}

export class VideoStreamingService {
  @ScalePredict({
    triggers: ['weekend-pattern', 'viral-content'],
    scaleUp: { before: '15m', factor: 2 },
  })
  async streamVideo() {
    /​/​ Demand signals recorded automatically
  }
}

Programmatic API

import { createPredictiveScaler, InMemoryScalingClient } from '@hazeljs/​predictive-scaling';

const scaler = createPredictiveScaler({
  horizon: '30m',
  metrics: ['requests'],
  hpa: { name: 'api-hpa', namespace: 'prod', client: new InMemoryScalingClient() },
});

scaler.recordMetric('requests', 420);
scaler.start();

await scaler.triggerEvent('black-friday');

Prometheus ingestion

import { createPredictiveScaler, attachPrometheusCollector } from '@hazeljs/​predictive-scaling';

const scaler = createPredictiveScaler({
  metrics: ['requests', 'latency', 'cpu'],
  hpa: { name: 'api-hpa', namespace: 'prod', client },
});

const prometheus = attachPrometheusCollector(scaler, {
  baseUrl: process.env.PROMETHEUS_URL ?? 'http://localhost:9090',
  pollIntervalMs: 60_000,
  queries: {
    requests: 'sum(rate(http_requests_total{service="api"}[5m]))',
    latency:
      'histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket{service="api"}[5m])) by (le))',
    cpu: 'avg(rate(container_cpu_usage_seconds_total{pod=~"api-.*"}[5m]))',
  },
});

scaler.start();
prometheus.start();

Combined ops stack

Reactive healing + proactive scaling on the same HPA client:

import { createOperationsStack } from '@hazeljs/​predictive-scaling';
import { InMemoryKubernetesScalingClient } from '@hazeljs/​self-healing';

const client = new InMemoryKubernetesScalingClient();

const ops = createOperationsStack({
  healing: {
    strategies: ['hpa-boost', 'pod-restart', 'config-rollback'],
    kubernetes: { deployment: 'payments-api', hpa: { name: 'payments-hpa', client } },
  },
  scaling: {
    horizon: '30m',
    metrics: ['requests', 'latency'],
    hpa: { name: 'payments-hpa', client },
  },
  prometheus: {
    baseUrl: 'http://prometheus.monitoring:9090',
    queries: { requests: 'sum(rate(http_requests_total[5m]))' },
  },
});

ops.start();

Recipes

Recipe: Predictive HPA

import { createPredictiveScaler, InMemoryScalingClient } from '@hazeljs/​predictive-scaling';

const scaler = createPredictiveScaler({
  horizon: '30m',
  confidence: 0.85,
  costOptimization: true,
  metrics: ['requests'],
  hpa: { name: 'api-hpa', namespace: 'prod', client: new InMemoryScalingClient() },
});
scaler.start();

Recipe: Operations stack

import { createOperationsStack } from '@hazeljs/​predictive-scaling';
import { InMemoryKubernetesScalingClient } from '@hazeljs/​self-healing';

const ops = createOperationsStack({
  healing: { kubernetes: { deployment: 'api', hpa: { name: 'api-hpa', client: new InMemoryKubernetesScalingClient() } } },
  scaling: { hpa: { name: 'api-hpa', client: new InMemoryKubernetesScalingClient() } },
});
ops.start();