Creates Cloud Cost Trends API doc, updates Allocation Trends content #835
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| # Cloud Cost Trends API | ||
|
|
||
| {% hint style="warning" %} This feature is only available in Kubecost Aggregator. For more information, see the release notes for [Kubecost V1.107](https://github.com/kubecost/cost-analyzer-helm-chart/releases/tag/v1.107.0). {% endhint %} | ||
|
|
||
| {% swagger method="get" path="/cloudCost/view/trends" baseUrl="http://<your-kubecost-address>/model" summary="Trends API" %} {% swagger-description %} Analyzes change in cloud costs relative to a previous window of the same size {% endswagger-description %} | ||
|
|
||
| {% swagger-parameter in="path" name="window" required="true" type="string" %} | ||
| Duration of time over which to query. Compares cost usage of window to cost usage window of equal size directly preceding it. Accepts all standard Kubecost window formats (See our doc on using [the `window` parameter](https://docs.kubecost.com/apis/apis-overview/assets-api#using-window-parameter)). | ||
| {% endswagger-parameter %} | ||
|
|
||
| {% swagger-parameter in="path" name="names" required="true" type="string" %} | ||
| Determines order sequence of queried items via comma-separated list. Dependent on the value of `aggregateBy` to list items. See more [below](cloud-cost-trends-api.md#using-the-names-parameter). | ||
| {% endswagger-parameter %} | ||
|
|
||
| {% swagger-parameter in="path" name="AggregateBy" type="string" required="false" %} | ||
| Field by which to aggregate the results. Accepts: `invoiceEntityID`, `accountID`, `provider`, `service`, and `label:<name>`. Supports multi-aggregation using comma-separated lists, such as `aggregate=accountID,service`. Defaults to `service`. | ||
| {% endswagger-parameter %} | ||
|
|
||
| {% swagger-parameter in="path" name="accumulate" type="boolean" required="false" %} | ||
| When set to `false`, returns daily time series data vs. cumulative data. Default is `true`. | ||
| {% endswagger-parameter %} | ||
|
|
||
| {% swagger-parameter in="path" name="CostMetricName" type="string" required="false" %} | ||
| Determines which cloud cost metric type will be returned. Acceptable values are `AmortizedNetCost`, `InvoicedCost`, `ListCost`, and `NetCost`. Default is `AmortizedNetCost`. | ||
| {% endswagger-parameter %} | ||
|
|
||
| {% swagger-parameter in="path" name="filter" type="string" required="false" %} | ||
| Filter your results by a particular category or value. For example, when to only see trends in AWS spend, set this parameter to `filter=provider:"AWS"`. Supports [Filter Parameters (v2)](https://docs.kubecost.com/apis/apis-overview/filters-api) language. | ||
| {% endswagger-parameter %} | ||
|
|
||
| {% swagger-response status="200: OK" description="" %} | ||
| <pre class="language-json"><code class="lang-json"><strong>{ | ||
| </strong> "code": 200, | ||
| "data": { | ||
| "trends": { | ||
| "": { | ||
| "isInfinite": false, | ||
| "isNaN": false, | ||
| "value": 0.000 | ||
| } | ||
| }, | ||
| "window": { | ||
| "start": "", | ||
| "end": "" | ||
| }, | ||
| "comparisonWindow": { | ||
| "start": "", | ||
| "end": "" | ||
| } | ||
| } | ||
| } | ||
| </code></pre> | ||
| {% endswagger-response %} | ||
| {% endswagger %} | ||
|
|
||
| ## Calculating trend value | ||
|
|
||
| The 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 `comparisonWindow`, 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 cloud cost data are sampled in order to provide an accurate value. | ||
|
|
||
| The equation for calculating `value` is: `value=window/comparisonWindow - 1` | ||
|
|
||
| Receiving a positive `value` means your `window` has increased compared to `comparisonWindow`. A negative `value` means spending has decreased. | ||
|
There was a problem hiding this comment. Should this be something like "Receiving a positive |
||
|
|
||
| {% hint style="warning" %} | ||
| 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. | ||
| {% endhint %} | ||
|
|
||
| In the example output below, `value` is expressed as `-0.147`, meaning spending has decreased for `project-123` by roughly 14.7% from the current week compared to the week before. | ||
|
|
||
| ```json | ||
| "trends": { | ||
| "project-123": { | ||
| "isInfinite": false, | ||
| "isNaN": false, | ||
| "value": -0.1472170691451784 | ||
| } | ||
| }, | ||
| "window": { | ||
| "start": "2023-11-29T00:00:00Z", | ||
| "end": "2023-12-06T00:00:00Z" | ||
| }, | ||
| "comparisonWindow": { | ||
| "start": "2023-11-22T00:00:00Z", | ||
| "end": "2023-11-29T00:00:00Z" | ||
| } | ||
| ``` | ||
|
|
||
| Trend values are converted into percentages in the Kubecost Cloud Costs Explorer 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. | ||
|
|
||
| ## Using the `names` parameter | ||
|
|
||
| `names` is a mandatory parameter which determines the sequence of items returned, based on whatever the query is aggregating by. For example, when `aggregateBy=provider`, the user should provide a comma-separated list of all items they which to see trend values for in this category. In this case, they should provide `names=AWS,GCP,Azure` to receive a list of trend values for all three providers. `service` is the default value for `AggregateBy`, so if the user does not provide a value for `aggregateBy`, they must still use the names parameter to list all services requested. For example, `names=AmazonEC2,AmazonS3,Microsoft.Compute...`. | ||
|
There was a problem hiding this comment. The actual parameter for aggregation is |
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm realizing now that we actually support more than this and that the default is not actually
servicebut an empty string. Using an empty string for aggregate would cause us to aggregate by item.As for a list of acceptable aggregate parameters, we can take
invoiceEntityID,accountID,provider,providerID,category,service, andlabel:<name>There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So if they don't provide a value for aggregate, they will have to list every single line item in Names for a complete breakdown of their trends?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes they would