Files
madmin-go/capacity-forecast.go

99 lines
3.8 KiB
Go

//
// Copyright (c) 2015-2026 MinIO, Inc.
//
// This file is part of MinIO Object Storage stack
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as
// published by the Free Software Foundation, either version 3 of the
// License, or (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <http://www.gnu.org/licenses/>.
package madmin
import (
"context"
"encoding/json"
"net/http"
)
// CapacityForecast contains storage capacity predictions based on
// historical daily snapshots processed through a Kalman filter.
//
// Days-until-threshold fields are pointers: nil means "unknown" (for example,
// not enough history yet, or usage is not growing). A concrete value may be
// negative when the threshold was already crossed in the past.
type CapacityForecast struct {
CurrentUsedBytes uint64 `json:"currentUsedBytes"`
CurrentTotalBytes uint64 `json:"currentTotalBytes"`
CurrentUsedPercent float64 `json:"currentUsedPercent"`
// Days until each usage threshold is reached. The projection comes from
// a Kalman filter that integrates up to 365 daily samples with greater
// weight on recent observations, so a fresh shift in usage dominates
// over older history. nil = unknown (slope is non-positive, or there
// is not enough history).
DaysUntil80Pct *float64 `json:"daysUntil80Pct,omitempty"`
DaysUntil90Pct *float64 `json:"daysUntil90Pct,omitempty"`
DaysUntil100Pct *float64 `json:"daysUntil100Pct,omitempty"`
// GrowthBytesPerDay is the Kalman filter slope expressed in bytes per
// day, projected from the daily snapshots in the circular buffer.
// It is independent of DailySnapshotCount: the filter is recency
// weighted, not a delta between two endpoints. It is a float64 so a
// slow, sub-byte-per-day slope is not truncated to zero.
GrowthBytesPerDay float64 `json:"growthBytesPerDay"`
// DailySnapshotCount is the number of valid daily snapshots currently
// held in the year-long circular buffer (range 0..365). The forecast
// fields above are only populated when this count reaches the
// minimum required for the filter to produce stable estimates.
DailySnapshotCount int `json:"dailySnapshotCount"`
// Worst-case prediction based on the largest single-day growth
// observed between any two consecutive data points. nil = unknown.
MinDaysUntilFull *float64 `json:"minDaysUntilFull,omitempty"`
// Variance is the population variance (divided by n, not the sample
// variance divided by n-1) of the day-to-day changes in usedFraction.
Variance float64 `json:"variance"`
// Smallest and largest day-to-day changes in used bytes observed
// between consecutive snapshots. A negative value means space was
// freed between those two days.
DayMinDeltaBytes int64 `json:"dayMinDeltaBytes"`
DayMaxDeltaBytes int64 `json:"dayMaxDeltaBytes"`
}
// CapacityForecast returns a storage capacity forecast based on
// historical daily snapshots.
func (adm *AdminClient) CapacityForecast(ctx context.Context) (CapacityForecast, error) {
resp, err := adm.executeMethod(ctx,
http.MethodGet,
requestData{
relPath: adminAPIPrefix + "/capacity-forecast",
})
defer closeResponse(resp)
if err != nil {
return CapacityForecast{}, err
}
if resp.StatusCode != http.StatusOK {
return CapacityForecast{}, httpRespToErrorResponse(resp)
}
var f CapacityForecast
if err = json.NewDecoder(resp.Body).Decode(&f); err != nil {
return CapacityForecast{}, err
}
return f, nil
}