Overview
You can use this document to learn how to use the StackPath API system to monitor the ingress and egress bandwidth of a workload.
Review available metrics
Bandwidth metrics can be pulled for an entire stack or for an individual workload. Bandwidth is always divided by StackPath PoP locations and will have to be summed for total use.
Endpoint: https://gateway.stackpath.com/workload/v1/stacks/<stack_id>/metrics
Method: GET
Query Parameters
type (String) (Required)
Set the value as "BANDWIDTH" to pull bandwidth metrics
start_date (Datetime) (Required)
Start Date specified the beginning of the reporting period over which the call pulls metrics from. If this period is before the date of workload creation, all values will be set to zero.
The datetime string should be in the standard datetime format YYYY-MM-DDTHH:MM:ss.sssZ
end_date (Datetime) (Required)
End Date specified the end of the reporting period over which the call pulls metrics from. If this period is after the current time, a JSON response with 'message': 'Unable to get metrics at this time'. will be returned.
The datetime string should be in the standard datetime format YYYY-MM-DDTHH:MM:ss.sssZ
workload_id (String) (Optional, Default: All Workloads)
Workload ID can be pulled from the URL in the StackPath Control Panel or from the Compute API GET workloads endpoint.
granularity(String) (Optional, Default: PT5M)
The summation period of metrics between the start_date and end_date.
- PT5M - 5 minutes
- PT1H - 1 hour
- P1D - 1 Day
PoP (String) (Optional, Default: ALL)
Filter traffic metrics by StackPath Point of Presence. Pull the possible location identifiers via the StackPath API Endpoint GET Locations.
Obtain daily metrics by workload
API Request
Method: GET
Endpoint: https://gateway.stackpath.com/workload/v1/stacks/{stack_id}/metrics
Payload
{
'start_date': '2019-03-23T14:54:18.442Z',
'end_date': '2019-03-24T14:54:18.442Z',
'wordload_id': "{stack_id}",
'type': "BANDWIDTH",
'granularity': 'P1D',
}
cURL Example
curl "https://gateway.stackpath.com/workload/v1/stacks/<stack_id>/metrics?start_date=2019-03-23T14:54:18.442Z&end_date=2019-03-24T14:54:18.442Z&workload_id=<workload_id>&type=BANDWIDTH&granularity=P1D" -H "Authorization: Bearer <token>"
Obtain hourly metrics by instance
API Request
Method: GET
Endpoint: https://gateway.stackpath.com/workload/v1/stacks/{stack_id}/metrics
Payload
{
'start_date': '2019-03-23T14:54:18.442Z',
'end_date': '2019-03-24T14:54:18.442Z',
'workload_id': "{stack_id}",
'instance_name': "{instance_hostname}"
'type': "BANDWIDTH",
'granularity': 'PT1H',
}
cURL Example
curl "https://gateway.stackpath.com/workload/v1/stacks/<stack_id>/metrics?start_date=2019-03-23T14:54:18.442Z&end_date=2019-03-24T14:54:18.442Z&workload_id=<workload_id>&instance_name=<instance_hostname>&type=BANDWIDTH&granularity=PT1H" -H "Authorization: Bearer <token>"
Obtain filtered metrics by PoP
API Request
Method: GET
Endpoint: https://gateway.stackpath.com/workload/v1/stacks/{stack_id}/metrics
Payload
{
'start_date': '2019-03-23T14:54:18.442Z',
'end_date': '2019-03-24T14:54:18.442Z',
'workload_id': "{stack_id}",
'type': "BANDWIDTH",
'granularity': 'P1D',
'pop': 'lhr02'
}
cURL Example
curl "https://gateway.stackpath.com/workload/v1/stacks/<stack_id>/metrics?start_date=2019-03-23T14:54:18.442Z&end_date=2019-03-24T14:54:18.442Z&workload_id=<workload_id>&type=BANDWIDTH&granularity=P1D&pop=lhr02" -H "Authorization: Bearer <token>"
Review response
Status Code: 200
{
"status":"success",
"data":{
"resultType":"matrix",
"result":[{
"metric":{
"__name__":"ingress_bandwidth",
"pop":"lhr02",
"traffic_region":"INTERNET"},
"values":[[1553385600,"2569901"]]},{
"metric":{
"__name__":"egress_bandwidth",
"pop":"lhr02",
"traffic_region":"INTERNET"},
"values":[[1553385600,"4442578"]]
}
]}
}
Each polling time period contains two types of results, ingress and egress. Ingress measures the inbound traffic to the compute instance, while egress measures outbound traffic from your instance. For each traffic region, the values list contains an epoch timestamp and the total amount of data in bytes.
Examining the response above, the epoch time "1553385600" translates to Sunday, March 24, 2019 12:00:00 AM and the public ingress of "2569901" bytes converts to 2.6MB.