forecaster

Documentation

Overview

Package main implements the core forecast loop orchestration.

This file contains the Forecaster type which orchestrates the forecast pipeline:

collect → buildFeatures → predict → calculateReplicas → storeSnapshot

The Forecaster runs continuously via Run(), executing Tick() at regular intervals. Each tick performs one complete forecast cycle, updating the stored snapshot that the scaler consumes via HTTP API.

The forecast loop is instrumented with Prometheus metrics tracking the duration of each pipeline stage (collect, predict, capacity planning) and any errors encountered during execution.

Command forecaster implements the Kedastral forecast engine.

The forecaster runs a continuous forecast loop that:

1. Collects historical metrics from Prometheus
2. Predicts future workload using a forecasting model
3. Calculates desired replica counts using capacity planning policies
4. Stores forecast snapshots for the scaler to consume
5. Exposes snapshots via HTTP API at /forecast/current

The forecaster serves an HTTP API on port 8081 (configurable) providing:

• GET /forecast/current?workload=<name> - Retrieve latest forecast snapshot
• GET /healthz - Health check endpoint
• GET /metrics - Prometheus metrics endpoint

Usage:

forecaster \
  -workload=my-api \
  -metric=http_rps \
  -prom-url=http://prometheus:9090 \
  -prom-query='sum(rate(http_requests_total[1m]))' \
  -target-per-pod=100 \
  -min=2 -max=50

Environment variables:

WORKLOAD       - Workload name (required)
METRIC         - Metric name (required)
PROM_URL       - Prometheus server URL
PROM_QUERY     - PromQL query (required)
TARGET_PER_POD - Target metric value per pod
MIN_REPLICAS   - Minimum replica count
MAX_REPLICAS   - Maximum replica count
HEADROOM       - Headroom multiplier (default: 1.2)
HORIZON        - Forecast horizon duration (default: 30m)
STEP           - Forecast step size (default: 1m)
INTERVAL       - Forecast loop interval (default: 30s)
LOG_LEVEL      - Logging level: debug, info, warn, error (default: info)
LOG_FORMAT     - Logging format: text, json (default: text)