Get metrics by using the Amazon CloudWatch API
You can use the CloudWatch API or Amazon Command Line Interface (Amazon CLI) to get the CloudFront metrics in programs or applications that you build. You can use the raw data to build your own custom dashboards, your own alarming tools, and so on.
For more information, see getmetricdata in the Amazon CLI Command Reference or the GetMetricData API operation in the Amazon CloudWatch API Reference.
Topics
Note
To get the CloudFront metrics from the CloudWatch API, you must use the US East (N. Virginia) Region
(useast1
). You also need to know certain values and types for
each metric.
Values for all CloudFront metrics
The following values apply to all CloudFront metrics:
Namespace

The value for
Namespace
is alwaysAWS/CloudFront
.  Dimensions

Each CloudFront metric has the following two dimensions:
DistributionId

The ID of the CloudFront distribution for which you want to get metrics.
FunctionName

The name of the function (in CloudFront Functions) for which you want to get metrics.
This dimension applies only to functions.
Region

The value for
Region
is alwaysGlobal
, because CloudFront is a global service.
Values for CloudFront distribution metrics
Use information from the following list to get details about specific CloudFront distribution metrics from the CloudWatch API. Some of these metrics are available only when you have turned on additional metrics for the distribution.
Note
Only one statistic, Average
or Sum
, is applicable
for each metric. The following list specifies which statistic is applicable to
that metric.
 4xx error rate

The percentage of all viewer requests for which the response's HTTP status code is
4xx
.
Metric name:
4xxErrorRate

Valid statistic:
Average

Unit:
Percent

 401 error rate

The percentage of all viewer requests for which the response's HTTP status code is
401
. To get this metric, you must first turn on additional metrics.
Metric name:
401ErrorRate

Valid statistic:
Average

Unit:
Percent

 403 error rate

The percentage of all viewer requests for which the response's HTTP status code is
403
. To get this metric, you must first turn on additional metrics.
Metric name:
403ErrorRate

Valid statistic:
Average

Unit:
Percent

 404 error rate

The percentage of all viewer requests for which the response's HTTP status code is
404
. To get this metric, you must first turn on additional metrics.
Metric name:
404ErrorRate

Valid statistic:
Average

Unit:
Percent

 5xx error rate

The percentage of all viewer requests for which the response's HTTP status code is
5xx
.
Metric name:
5xxErrorRate

Valid statistic:
Average

Unit:
Percent

 502 error rate

The percentage of all viewer requests for which the response's HTTP status code is
502
. To get this metric, you must first turn on additional metrics.
Metric name:
502ErrorRate

Valid statistic:
Average

Unit:
Percent

 503 error rate

The percentage of all viewer requests for which the response's HTTP status code is
503
. To get this metric, you must first turn on additional metrics.
Metric name:
503ErrorRate

Valid statistic:
Average

Unit:
Percent

 504 error rate

The percentage of all viewer requests for which the response's HTTP status code is
504
. To get this metric, you must first turn on additional metrics.
Metric name:
504ErrorRate

Valid statistic:
Average

Unit:
Percent

 Bytes downloaded

The total number of bytes downloaded by viewers for
GET
,HEAD
, andOPTIONS
requests.
Metric name:
BytesDownloaded

Valid statistic:
Sum

Unit:
None

 Bytes uploaded

The total number of bytes that viewers uploaded to your origin with CloudFront, using
POST
andPUT
requests.
Metric name:
BytesUploaded

Valid statistic:
Sum

Unit:
None

 Cache hit rate

The percentage of all cacheable requests for which CloudFront served the content from its cache. HTTP
POST
andPUT
requests, and errors, are not considered cacheable requests. To get this metric, you must first turn on additional metrics.
Metric name:
CacheHitRate

Valid statistic:
Average

Unit:
Percent

 Origin latency

The total time spent, in milliseconds, from when CloudFront receives a request to when it starts providing a response to the network (not the viewer), for requests that are served from the origin, not the CloudFront cache. This is also known as first byte latency, or timetofirstbyte. To get this metric, you must first turn on additional metrics.

Metric name:
OriginLatency

Valid statistic:
Percentile

Unit:
Milliseconds
Note
To get a
Percentile
statistic from the CloudWatch API, use theExtendedStatistics
parameter, notStatistics
. For more information, see GetMetricStatistics in the Amazon CloudWatch API Reference, or the reference documentation for the Amazon SDKs. 
 Requests

The total number of viewer requests received by CloudFront, for all HTTP methods and for both HTTP and HTTPS requests.

Metric name:
Requests

Valid statistic:
Sum

Unit:
None

 Total error rate

The percentage of all viewer requests for which the response's HTTP status code is
4xx
or5xx
.
Metric name:
TotalErrorRate

Valid statistic:
Average

Unit:
Percent

Values for CloudFront function metrics
Use information from the following list to get details about specific CloudFront function metrics from the CloudWatch API.
Note
Only one statistic, Average
or Sum
, is applicable
for each metric. The following list specifies which statistic is applicable to
that metric.
 Invocations

The number of times the function was started (invoked) in a given time period.

Metric name:
FunctionInvocations

Valid statistic:
Sum

Unit:
None

 Validation errors

The number of validation errors produced by the function in a given time period. Validation errors occur when the function runs successfully but returns invalid data (an invalid event object).

Metric name:
FunctionValidationErrors

Valid statistic:
Sum

Unit:
None

 Execution errors

The number of execution errors that occurred in a given time period. Execution errors occur when the function fails to complete successfully.

Metric name:
FunctionExecutionErrors

Valid statistic:
Sum

Unit:
None

 Compute utilization

The amount of time (0100) that the function took to run as a percentage of the maximum allowed time. For example, a value of 35 means that the function completed in 35% of the maximum allowed time.

Metric name:
FunctionComputeUtilization

Valid statistic:
Average

Unit:
Percent

 Throttles

The number of times that the function was throttled in a given time period.

Metric name:
FunctionThrottles

Valid statistic:
Sum

Unit:
None
