Retrieving Stack Metrics
This guide describes the process of fetching CDN metrics for all sites on a Stack. It assumes a Stack exists with at least one configured CDN site, and that site serves traffic. Metrics may take up to 15 minutes to show up in the API.
Required Fields
The following fields are required in order to retrieve a Stack's bandwidth metrics:
start_date
end_date
platform
granularity
Start and End Dates
The start_date
and end_date
fields are ISO 8601 dates in the format YYYY-MM-DDTHH:MM:SSZ
and are always in UTC.
Granularity
Granularity is based off of the ISO 8601 duration format, and the following options are supported:
PT5M
: Five minute granularity begins at the top of the hour and at each five-minute interval and ends after five minutes.PT1H
: Hourly granularity begins at the top of the hour and ends just before the end of the hour.P1D
: Daily granularity begins at midnight and ends just before the next midnight.P1M
: Monthly granularity begins at midnight of the first day of the month and ends just before midnight of the last day of the month.
Platforms
Platforms are how we categorize different types of traffic on our network. For instance, the CDE
platform is reserved for tracking CDN traffic that leaves our edge nodes bound for the client who requests resources from StackPath's CDN. This is the platform used to bill customers for bandwidth.
Other platforms are useful from a reporting perspective as well. For instance, CDO
is the platform that tracks how much traffic is ingested from the origin for a CDN site. This traffic is not billed, but customers may want to know how many times assets were fetched from the origin and how much bandwidth was consumed to do so.
Please refer to the table below for a list of all of the available platforms along with their descriptions:
Platform | Description |
---|---|
CDE | Tracks the traffic that travels from the CDN to the end-user. This is also the platform StackPath uses to bill customers for bandwidth. This value is calculated using the following formula: CDE = CDS + SDS - CDI - SDI |
CDO | Tracks the traffic that travels from the origin to the CDN. This value is calculated using the following formula: CDO = CDI + SDI |
CDI | Content Delivery Ingest. HTTP ingest from origin. |
SDI | Secured Content Delivery Ingest. HTTPS ingest from origin. |
CDP | Delivery from Proxy Port |
SDS | Secured Content Delivery Service (HTTPS). Delivery to end-user. |
CDS | Content Delivery Service (HTTP). Delivery to end-user. |
CDD | Content Shield Delivery |
CDM | Content Mid-Tier Cache Pull |
CDR | Client Delivery Receipts |
SES | Script Engine Service (PHP) |
SDM | Secure Mid-Tier Cache Pull |
CDDE | Content Delivery Distribution Egress (Shield) |
WDS | WAF content delivery. To be used for WAF-only sites. |
WSS | WAF content delivery (Secure). To be used for WAF-only sites. |
WSI | WAF origin ingest (Secure). Ingest between WAF and the origin. |
WDI | WAF origin ingest. Ingest between WAF and the origin. |
WDD | WAF delivery shield |
WSD | WAF delivery shield (Secure) |
SLC | Serverless Compute (EdgeEngine). Bytes that went through Serverless. |
CWS | Content WebSocket Service |
SWS | Secure Content WebSocket Service |
CWI | Content WebSocket Ingest |
SWI | Secure Content WebSocket Ingest |
Example
In the example below, we are going to be retrieving our Stack's bandwidth metrics by making a call to the Get metrics endpoint.
CDE
is the platform we are interested in and P1D
is used for the granularity. This returns all outbound traffic for the entire month as a set of data points.
curl "https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/metrics?start_date=2019-02-11T00:00:00Z&end_date=2019-02-11T23:59:59Z&platforms=CDE&granularity=P1D" \
-H "Authorization: bearer BEARER_TOKEN" \
-H "Content-Type: application/json"
This request returns a JSON object that looks something like this:
{
"series": [
{
"key": "17t4x4d8",
"metrics": [
"usageTime",
"xferUsedTotalMB",
"xferUsedMinMB",
"xferUsedMaxMB",
"xferUsedMeanMB",
"xferAttemptedTotalMB",
"durationTotal",
"xferRateMaxMbps",
"xferRateMaxUsageTime",
"xferRateMinMbps",
"xferRateMinUsageTime",
"xferRateMeanMbps",
"requestsCountTotal",
"requestsCountMin",
"requestsCountMax",
"requestsCountMean",
"rpsMax",
"rpsMaxUsageTime",
"rpsMin",
"rpsMinUsageTime",
"rpsMean",
"lastUpdatedTime",
"xferRateMbps",
"userXferRateMbps",
"rps",
"completionRatio",
"responseSizeMeanMB",
"peakToMeanMBRatio",
"peakToMeanRequestsRatio"
],
"samples": [
{
"values": [
1549843200000,
6.221916,
0,
4.147944,
0.021604566324,
6.221916,
22466,
0.11061184,
1549843200000,
0,
1549843200000,
0.00057612176864,
1291,
0,
652,
5,
2.1733333333333,
1549843200000,
0,
1549843200000,
0.016666666666667,
1549934069460.2,
0.00057610333333333,
2.215584794801,
0.01494212962963,
1,
0.0048194546862897,
191.9938561966,
130.4
]
}
]
}
]
}
Metrics Definitions
As you can see, metrics names are returned first. This describes the order that the sample values in the JSON object are represented. Here's what they are:
xferUsedTotalMB
: total MB transferredxferUsedMinMB
: minimum five minute bucket of MB transferredxferUsedMaxMB
: maximum five minute bucket of MB transferredxferUsedMeanMB
: average of five minute buckets of MB transferredxferAttemptedTotalMB
: total MB attempteddurationTotal
: total transfer time of all requestsxferRateMaxMbps
: maximum transfer ratexferRateMaxUsageTime
: timestamp at which maximum transfer rate occurredxferRateMinMbps
: minimum transfer ratexferRateMinUsageTime
: timestamp at which minimum transfer rate occurredxferRateMeanMbps
: average transfer raterequestsCountTotal
: total requestsrequestsCountMin
: minimum five minute bucket of requests per secondrequestsCountMax
: maximum five minute bucket of requests per secondrequestsCountMean
: average of five minute bucket requests per secondrpsMax
: maximum requests per secondrpsMaxUsageTime
: timestamp at which maximum requests per second occurredrpsMin
: minimum requests per secondrpsMinUsageTime
: timestamp at which minimum requests per second occurredrpsMean
: mean requests per secondlastUpdatedTime
: last time this bucket was updatedxferRateMbps
: average transfer rate in MbpsuserXferRateMbps
: total transfer divided by durationrps
: requests per second, calculated as total requests divided by number of seconds in bucketcompletionRatio
: completed requests divided by attempted requestsresponseSizeMeanMB
: total MB transferred divided by number of requestspeakToMeanMBRatio
: maximum transfer rate divided by mean transfer ratepeakToMeanRequestsRatio
: maximum requests per second divided by mean requests per second
xferUsedTotalMB
is the only one of these metrics used for billing. The others are provided for additional visibility into usage on the platform.
Updated 5 months ago