Skip to content
API Enriched

Usage Metrics.

POST
/api/data/namespaces/{namespace}/workloads/usage
curl --request POST \
  --url https://example-corp.console.ves.volterra.io/api/v1/api/production/us-east-1/namespaces/default/api/data/namespaces/example/workloads/usage \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "end_time": "example", "field_selector": [ "CPU_USAGE" ], "filter": "example", "group_by": [ "NAMESPACE" ], "include_system_workloads": true, "namespace": "example", "range": "example", "start_time": "example", "step": "example" }'

GET the workload usage.

Examples of this operation.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
namespace
required
string

Namespace namespace is used to scope the workload usage to a given namespace.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
Usage Request

Request to GET workload usage in the given namespace.

object
end_time
End time

End time of metric collection from which data will be considered to build graph. Format: unix_timestamp|RFC 3339

Optional: If not specified, then the end_time will be evaluated to start_time+10m If start_time is not specified, then the end_time will be evaluated to

string
<= 1024 characters
field_selector
Field Selector

Select fields to be returned in the response. One or more fields in {CPU_USAGE, MEMORY_USAGE, DISK_READS, DISK_WRITES} can be specified.

Required: YES.

Array<string>
>= 1 items <= 8 items
Allowed values: CPU_USAGE MEMORY_USAGE DISK_READS DISK_WRITES
filter
Label Filter

Filter is used to specify the list of matchers syntax for filter := {[]} :=

Optional: If not specified, all workloads usage in the given namespace will be aggregated based on the group_by field.

string
<= 1024 characters
group_by
Group by

Aggregate data by zero or more labels {NAMESPACE, CONTAINER, POD, SITE}

Array<string>
Allowed values: NAMESPACE CONTAINER POD SITE WORKLOAD
include_system_workloads
Include System Workloads

Allows user to specify if the usage of system workloads (such as pods running in F5 Distributed Cloud namespaces and the Kubernetes pods) should be included in the response. This field is applicable only in the system namespace where the response contains data across all namespaces.

Optional: If not specified, only the workloads running in the customer namespaces would be returned in the response.

boolean format: boolean
namespace
Namespace

Namespace is used to scope the workload usage to a given namespace.

string
>= 6 characters <= 1024 characters
range
Range

Range decides how far to go back in time to fetch values for each step. For example, if the range is 5m, then for step t1, query will be evaluated for t1-5m and for t2, query will be evaluated for t2-5m and so on. Format: [0-9][smhd], where s - seconds, m - minutes, h - hours, d - days

Note: For non-timeseries query, i.e., for step=end_time-start_time, range should be set to end_time-start_time

Optional: If not specified, range is set to 5m.

string
<= 1024 characters
start_time
Start time

Start time of metric collection from which data will be considered to build graph. Format: unix_timestamp|RFC 3339

Optional: If not specified, then the start_time will be evaluated to end_time-10m If end_time is not specified, then the start_time will be evaluated to -10m.

string
<= 1024 characters
step
Step

Step is the resolution width, which determines the number of the data points [x-axis (time)] to be returned in the response. The timestamps in the response will be t1=start_time, t2=t1+step, … Tn=tn-1+step, where tn <= end_time. Format: [0-9][smhd], where s - seconds, m - minutes, h - hours, d - days

Optional: If not specified, then step size is evaluated to <end_time - start_time>

string
<= 1024 characters

Responses

Section titled “Responses”

200

Section titled “200”

A successful response.

Media typeapplication/json
Usage Response

Workload usage response.

object
data
Data

Data contains time-series data for the workload usage.

Array<object>
Usage Data

Usage data contains the usage type and the corresponding metric.

object
data
Data

List of metric data.

Array<object>
Usage Type Data

Usage Type Data contains key/value pair that uniquely identifies a workload in the response and the corresponding metric data.

object
key
Key

Key contains the name/value pair. “name” is the label name defined in “UsageLabel”

object
value
Value

List of metric values.

Array<object>
>= 3 characters <= 15 characters
Metric Value

Metric data contains timestamp and the value.

object
timestamp
Timestamp

Timestamp

number format: double
trend_value
object
description
Description

Description of the method used to calculate trend.

string
>= 21 characters <= 1024 characters
previous_value
Previous Value

Configuration parameter for previous value

string
<= 1024 characters
sentiment
string
default: TREND_SENTIMENT_NONE
Allowed values: TREND_SENTIMENT_NONE TREND_SENTIMENT_POSITIVE TREND_SENTIMENT_NEGATIVE
value
Value

Configuration parameter for value

string
>= 3 characters <= 1024 characters
value
Value

Configuration parameter for value

string
>= 3 characters <= 1024 characters
type
string
default: CPU_USAGE
Allowed values: CPU_USAGE MEMORY_USAGE DISK_READS DISK_WRITES
unit
string
default: UNIT_MILLISECONDS
Allowed values: UNIT_MILLISECONDS UNIT_SECONDS UNIT_MINUTES UNIT_HOURS UNIT_DAYS UNIT_BYTES UNIT_KBYTES UNIT_MBYTES UNIT_GBYTES UNIT_TBYTES UNIT_KIBIBYTES UNIT_MIBIBYTES UNIT_GIBIBYTES UNIT_TEBIBYTES UNIT_BITS_PER_SECOND UNIT_BYTES_PER_SECOND UNIT_KBITS_PER_SECOND UNIT_KBYTES_PER_SECOND UNIT_MBITS_PER_SECOND UNIT_MBYTES_PER_SECOND UNIT_CONNECTIONS_PER_SECOND UNIT_ERRORS_PER_SECOND UNIT_PACKETS_PER_SECOND UNIT_REQUESTS_PER_SECOND UNIT_PACKETS UNIT_PERCENTAGE UNIT_COUNT
step
step

Actual step size used in the response. It could be higher than the requested step due to metric rollups and the query duration. Format: [0-9][smhd], where s - seconds, m - minutes, h - hours, d - days.

string
<= 1024 characters
Example
{
  "data": [
    {
      "data": [
        {
          "value": [
            {
              "trend_value": {
                "sentiment": "TREND_SENTIMENT_NONE"
              }
            }
          ]
        }
      ],
      "type": "CPU_USAGE",
      "unit": "UNIT_MILLISECONDS"
    }
  ]
}

401

Section titled “401”

Returned when operation is not authorized.

Media typeapplication/json
string format: string
Examplegenerated
example

403

Section titled “403”

Returned when there is no permission to access resource.

Media typeapplication/json
string format: string
Examplegenerated
example

404

Section titled “404”

Returned when resource is not found.

Media typeapplication/json
string format: string
Examplegenerated
example

409

Section titled “409”

Returned when operation on resource is conflicting with current value.

Media typeapplication/json
string format: string
Examplegenerated
example

429

Section titled “429”

Returned when operation has been rejected as it is happening too frequently.

Media typeapplication/json
string format: string
Examplegenerated
example

500

Section titled “500”

Returned when server encountered an error in processing API.

Media typeapplication/json
string format: string
Examplegenerated
example

503

Section titled “503”

Returned when service is unavailable temporarily.

Media typeapplication/json
string format: string
Examplegenerated
example

504

Section titled “504”

Returned when server timed out processing request.

Media typeapplication/json
string format: string
Examplegenerated
example