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:

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 transferred
• xferUsedMinMB: minimum five minute bucket of MB transferred
• xferUsedMaxMB: maximum five minute bucket of MB transferred
• xferUsedMeanMB: average of five minute buckets of MB transferred
• xferAttemptedTotalMB: total MB attempted
• durationTotal: total transfer time of all requests
• xferRateMaxMbps: maximum transfer rate
• xferRateMaxUsageTime: timestamp at which maximum transfer rate occurred
• xferRateMinMbps: minimum transfer rate
• xferRateMinUsageTime: timestamp at which minimum transfer rate occurred
• xferRateMeanMbps: average transfer rate
• requestsCountTotal: total requests
• requestsCountMin: minimum five minute bucket of requests per second
• requestsCountMax: maximum five minute bucket of requests per second
• requestsCountMean: average of five minute bucket requests per second
• rpsMax: maximum requests per second
• rpsMaxUsageTime: timestamp at which maximum requests per second occurred
• rpsMin: minimum requests per second
• rpsMinUsageTime: timestamp at which minimum requests per second occurred
• rpsMean: mean requests per second
• lastUpdatedTime: last time this bucket was updated
• xferRateMbps: average transfer rate in Mbps
• userXferRateMbps: total transfer divided by duration
• rps: requests per second, calculated as total requests divided by number of seconds in bucket
• completionRatio: completed requests divided by attempted requests
• responseSizeMeanMB: total MB transferred divided by number of requests
• peakToMeanMBRatio: maximum transfer rate divided by mean transfer rate
• peakToMeanRequestsRatio: 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.