Allocation Trends API
Allocation Trends API
GET
http://<your-kubecost-address>/model/allocation/trends
Path Parameters
Name | Type | Description |
---|---|---|
window* | string | |
names* | string | Determines order sequence of queried items via comma-separated list. Dependent on the value of |
aggregate | string | Field by which to aggregate the results. Accepts: |
accumulate | boolean | When set to |
external | string | If |
idle | boolean | If |
filterNamespaces | string | Comma-separated list of namespaces to match; e.g. |
shareIdle | boolean | If true, idle cost is allocated proportionally across all non-idle allocations, per-resource. That is, idle CPU cost is shared with each non-idle allocation's CPU cost, according to the percentage of the total CPU cost represented. Default is false. |
shareNamespaces | string | Comma-separated list of namespaces to share; e.g. |
shareLabels | string | Comma-separated list of labels to share; e.g. |
shareCost | float | Floating-point value representing a monthly cost to share with the remaining non-idle, unshared allocations; e.g. |
shareTenancyCosts | boolean | If |
idleByNode | boolean | If |
splitIdle | boolean | If |
reconcile | boolean | If |
Calculating trend value
The Allocation Trends API determines changes in resource cost usage over time based on the interval set window
parameter and provides that information via the schema field value
. Cost usage for the current window sampled will be compared with the previous window, the window directly before the current window of the same size interval. For example, for window=3d
, Kubecost will output cost usage for the past three days compared to cost usage of the three days before the start of the window. This means a total of six days of allocation data must be available and sampled in order to provide an accurate value.
The equation for calculating value
is: value=current/previous - 1
Receiving a positive value
means your more recent totalCost
has increased compared to the previous window. A negative value
means spending has decreased.
It's important to recognize when a resource is not detected to exist in the previous window. This is designated by the field IsInfinite=true
, which means the allocation could not be determined to exist. Otherwise, the cause of an unexpected or major trend change could be misattributed. The field isNaN
, meaning not a number, refers to if the value
is unreal. If so, isNan
should return true
, which means there was an error during calculation. Both fields should return false
during a successful query.
In the example output below, value
is expressed as -0.27...
, meaning spending has decreased in the current window by roughly 27% from the previous window.
Using the names
parameter
names
parameternames
is a mandatory parameter which determines the sequence of items returned, based on whatever the query is aggregating by. For example, when using aggregate=namespace
, the user should provide a comma-separated list of all namespaces they wish to see trend values for in this category. In this case, they should provide names=kubecost,aggregator,kube-system...
to receive a list of trend values for all provided namespaces as ordered. If the user does not provide a value for aggregate
, they must still use the names parameter to list all line items requested.
Viewing trend percentages in the UI
Trend values are converted into percentages in the Kubecost Allocations page, calculated based on your current query. Trends will be presented in the rightmost column, next to your Total cost. The window
parameter is determined by your selected date range in the top right of the page. The default is Last 7 days (window=7d
). The equation value*100
is used to provide percentages.
![](https://docs.kubecost.com/~gitbook/image?url=https%3A%2F%2F1804196253-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FiPW99yDnU7U1FFgLgPOZ%252Fuploads%252Fgit-blob-20bb2410192cd025e58c2a9ac8bae27cda7126ef%252Ftotal-cost.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=9b6289c9&sv=1)
Requests with large time intervals for window
can result in an error. The recommended maximum interval for window
is 7 days. A failed response will show a N/A inside a gray bubble in the UI with no percentage returned.
The Trends API does not currently support cost comparisons besides totalCost
.
Last updated