Getting 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. All API calls within this guide are described in our CDN service API documentation.

Getting Bandwidth Metrics

These fields are required:

• start_date
• end_date
• platform
• granularity

The start_date and end_date fields are ISO 8601 dates in the format YYYY-MM-DDTHH:MM:SSZ and are always in UTC.

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.

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.

In the example below, CDE is used for the platform and P1D is used for the granularity. This returns all outbound traffic for the entire month as a set of data points. Replace STACK_ID with your stack ID, and replace BEARER_TOKEN with your own token.

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.

If you have a request, comment, or just want to say hi please send an email. If you need immediate assistance our 24/7 support is here to help.