Access Logs

You can enable CloudFront to deliver access logs per distribution to an Amazon S3 bucket of your choice. The following figure and table describe the basic process for access logs.

Process for Access Logs

	Your end users use your application or website. In this graphic, you have two different websites, A and B, each using a different CloudFront distribution (Distribution A and Distribution B).
	Your end users send requests for content, and CloudFront routes each request to the appropriate edge location.
	CloudFront writes data about each request to a log file specific to that distribution. In this graphic, CloudFront writes information about requests related to Distribution A in a log file just for Distribution A, and requests for Distribution B in a log file just for Distribution B.
	CloudFront periodically puts the distribution's log file in an Amazon S3 bucket of your choice, and then starts writing a new log file for the distribution.

You can store each distribution's log files in the same bucket as your origin server or a different one. Each entry in a log file gives details about a single end user request for an object. You can have multiple distributions' log files delivered to the same bucket. When you enable logging for a particular distribution, you can specify an optional log filename prefix. Log files are delivered to your bucket within 24 hours of the end user's access, and typically sooner than that.

	Note
	Because logs for a single stream can get recorded in multiple files, we recommend you combine all the log files you receive for a given period into one file. You can then analyze the data for that period more quickly and accurately.

Important

You should use the logs to understand the nature of the requests for your content, not as a complete accounting of all requests. CloudFront delivers access logs on a best-effort basis. The log record for a particular request might be delivered long after the request was actually processed, or not at all. In rare cases, usage that appears in the AWS usage tracking and billing systems might not appear in CloudFront access logs.

You must have Amazon S3 FULL_CONTROL permission for the log file bucket. You have this permission by default if you're the bucket owner. If you're not, the bucket owner must grant your AWS account FULL_CONTROL permission.

When you enable logging, you do it with an API call to the CloudFront control API. Making that API call also automatically calls the Amazon S3 API to update the bucket's ACL to allow read and write permissions for the AWS data feeds account. This account writes the log files to the bucket.

Each log file has its own ACL (separate from the bucket's ACL). The bucket owner has FULL_CONTROL permission for the log files, the distribution owner (if not the bucket owner) has no permission, and the data feeds account has read and write permission.

	Note
	Removing the permissions for the data feeds account does not disable logging. If you remove those permissions, but don't disable logging (which you do with the control API), we reinstate those permissions the next time the data feeds account needs to write a log file to your log bucket.

If you disable logging, we don't remove the read/write permissions for the data feeds account on either the bucket or the log files. If you want, you can do that yourself.

To enable or disable CloudFront access logs, you must use the 2009-04-02 or later version of the CloudFront control API for download distributions, and the 2010-05-01 or later version of the CloudFront control API for streaming distributions.

	Note
	If a distribution has no end user requests during a particular hour, you don't receive a log file for that hour.

For more information, see the following documentation:

The Logging element includes two child elements: one for the Amazon S3 bucket to hold the logs, and one for the optional filename prefix of your choice.

	Note
	To enable easier listing of keys in a bucket, Amazon S3 users commonly use a prefix along with a slash (/) as a delimiter. CloudFront doesn't allow a prefix to begin with a slash; however, the prefix can end in one. The examples presented here have a slash appended following the prefix.

The following example shows a distribution's configuration with the Logging element.

<DistributionConfig xmlns="http://cloudfront.amazonaws.com/doc/2010-11-01/">
   <S3Origin>
      <DNSName>myawsbucket.s3.amazonaws.com</DNSName>
   </S3Origin>
   <CallerReference>20120229090000</CallerReference>
   <Comment>My comments</Comment>
   <Enabled>true</Enabled>
   <Logging>
      <Bucket>myawslogbucket.s3.amazonaws.com</Bucket>
      <Prefix>myprefix/</Prefix>
   </Logging>
</DistributionConfig>

You must specify the Amazon S3 bucket using this format: <bucket name>.s3.amazonaws.com. Do not use the Amazon S3 path style for specifying the bucket, which is s3.amazonaws.com/<bucket name>.

If you don't want to use a filename prefix, include an empty Prefix element, as shown in the following example. CloudFront doesn't substitute a default prefix. However, the XML is invalid if you omit the Prefix element entirely.

<DistributionConfig xmlns="http://cloudfront.amazonaws.com/doc/2010-11-01/">
   <S3Origin>
      <DNSName>myawsbucket.s3.amazonaws.com</DNSName>
   </S3Origin>
   <CallerReference>20120229090000</CallerReference>
   <Comment>My comments</Comment>
   <Enabled>true</Enabled>
   <Logging>
      <Bucket>myawslogbucket.s3.amazonaws.com</Bucket>
      <Prefix/>
   </Logging>
</DistributionConfig>

CloudFront does not automatically delete log files from the Amazon S3 bucket that you specified when you enabled logging. For information about deleting log files from an Amazon S3 bucket, see the applicable Amazon S3 documentation:

At any time, you can update a distribution's logging configuration to use a different bucket or filename prefix. When you update the logging configuration, your changes take effect within 12 hours.

	Important
	Whenever you update the Logging element, you must provide both the Bucket and Prefix child elements. If you don't have a prefix, the Prefix element will be empty.

For more information about updating a distribution's configuration, see Updating a Distribution's Configuration.

The filename follows this format (with the date and hour in UTC):

{Bucket}.s3.amazonaws.com/{Optional Prefix You Choose}{Distribution ID}.{YYYY}-{MM}-{DD}-{HH}.{Unique ID}.gz

For example, if your bucket name is mylogs, and you name your prefix myprefix/, your filenames look similar to this:

mylogs.s3.amazonaws.com/myprefix/EMLARXS9EXAMPLE.2009-03-17-20.RT4KCN4SGK9.gz

Log files arrive in your bucket typically once an hour.

Each hour of usage is typically covered in a single log file. CloudFront compresses the file in gzip format before delivering it to your bucket. CloudFront might write multiple files for a given hour of usage. For example, this occurs if the log file contents for the hour exceed 50 MB (uncompressed).

	Note
	If a distribution has no end user requests during a particular hour, you don't receive a log file for that hour.

The fields in download and streaming distribution log files are different. Both log files, however:

Download Distribution File Format

The following table describes the fields for one record in the download distribution log file.

Field	Description
c-ip	Client IP, for example, 192.0.2.183.
cs(Host)	DNS name (the CloudFront distribution name specified in the request). If you made the request to a CNAME, the DNS name field will contain the underlying distribution DNS name, not the CNAME.
cs-method	HTTP access method.
cs(Referer)	The referrer.
cs(User-Agent)	The user agent.
date	The date (UTC) on which the event occurred, for example, 2009-03-10.
s-uri-stem	URI stem (e.g., /images/daily-ad.jpg).
sc-bytes	Server to client bytes, for example, 1045619.
sc-status	HTTP status code (e.g., 200).
time	Time when the server finished processing the request (UTC), for example, 01:42:39.
x-edge-location	The edge location that served the request. Each edge location is identified by a three-letter code and an arbitrarily assigned number, for example, DFW3. The three-letter code typically corresponds with the International Air Transport Association airport code for an airport near the edge location. (These abbreviations may change in the future.) For a list of edge locations, see the Amazon CloudFront detail page, http://aws.amazon.com/cloudfront.
cs-uri-query	The query string portion of the URI that is included on the connect string. When a URI doesn't contain a query string, the log file contains a single dash (-). The log records query strings to a maximum length of 8K bytes. The encoding standard is RFC 1738, as described in Log File Format

	Note
	Question marks (?) in URLs and query strings are not included in the log.

The fields appear in the following order in a record:

• date

• time

• x-edge-location

• sc-bytes

• c-ip

• cs-method

• cs(Host)

• cs-uri-stem

• sc-status

• cs(Referer)

• cs(User Agent)

• cs-uri-query

The following is an example log file for a download distribution.

#Version: 1.0
#Fields: date time x-edge-location sc-bytes c-ip cs-method cs(Host) cs-uri-stem sc-status cs(Referer) cs(User-Agent) cs-uri-query
02/01/2011 01:13:11 FRA2 182 192.0.2.10 GET d2819bc28.cloudfront.net /view/my/file.html 200 www.displaymyfiles.com Mozilla/4.0%20(compatible;%20MSIE%205.0b1;%20Mac_PowerPC) -
02/01/2011 01:13:12 LAX1 2390282 192.0.2.202 GET www.singalong.com /soundtrack/happy.mp3 304 www.unknownsingers.com Mozilla/4.0%20(compatible;%20MSIE%207.0;%20Windows%20NT%205.1) a=b&c=d 

Streaming Distribution Log File Format

Each record in a streaming access log represents a playback event, for example, connect, play, pause, stop, disconnect, and so on. So, CloudFront generates multiple log records each time a viewer watches a video. To relate log records that stem from the same stream ID, use the x-sid field.

	Note
	Some fields are present for all events, whereas others appear only on Play, Stop, Pause, Unpause, and Seek events. When a field isn't relevant for a given event, the log file will contain a single dash (-).

The following table describes the fields that are present on each record in the streaming distribution log file, regardless of the type of event.

Field	Description
date	Date (UTC) on which the event occurred.
time	Time when the server received the request (UTC), for example, 01:42:39.
x-edge-location	The edge location where the playback event occured. Each edge location is identified by a three-letter code and an arbitrarily assigned number, for example, DFW3. The three-letter code typically corresponds with the International Air Transport Association airport code for an airport near the edge location. (These abbreviations may change in the future.) For a list of edge locations, see the Amazon CloudFront detail page, http://aws.amazon.com/cloudfront.
c-ip	Client IP, for example, 192.0.2.183.
x-event	The event type. This is a Connect, Disconnect, Play, Stop, Pause, Unpause, or Seek event.
sc-bytes	The running total number of bytes sent from the server to the client, up to the time of the event.
x-cf-status	A code indicating the status of the event. Currently, "OK" is the only value for this field. New functionality in the future could require new status codes.
x-cf-client-id	An opaque string identifier that can be used to differentiate clients This value is unique for each connection.
cs-uri-stem	The stem portion of the URI, including the application and the application instance. This is sometimes referred to as the FMS connect string. For example, rtmp://shqshne4jdp4b6.cloudfront.net/cfx/st.
cs-uri-query	The query string portion of the URI that is included on the connect string.
c-referrer	The URI of the referrer.
x-page-url	The URL of the page from which the SWF is linked.
c-user-agent	The user agent.

The following fields are present only on Play, Stop, Pause, Unpause, and Seek events. For other events, these fields will contain a single dash (-).

Field	Description
x-sname	The stream name.
x-sname-query	The stream query string, if any.
x-file-ext	The stream type, for instance, FLV.
x-sid	The stream ID. This is a unique integer identifier for the connection.

	Note
	Question marks (?) in URLs and query strings are not included in the log.

The fields appear in the following order in a record:

• date

• time

• x-edge-location

• c-ip

• x-event

• sc-bytes

• x-cf-status

• x-cf-client-id

• cs-uri-stem

• cs-uri-query

• c-referrer

• x-page-url

• c-user-agent

• x-sname

• x-sname-query

• x-file-ext

• x-sid

The following is an example of a log file for a streaming distribution.

#Version: 1.0
#Fields: date time x-edge-location c-ip x-event sc-bytes x-cf-status x-cf-client-id cs-uri-stem cs-uri-query c-referrer x-page-url​  c-user-agent x-sname x-sname-query x-file-ext x-sid
2010-03-12   23:51:20   SEA4   192.0.2.147   connect   2014   OK   bfd8a98bee0840d9b871b7f6ade9908f   rtmp://shqshne4jdp4b6.cloudfront.net/cfx/st​  key=value   http://player.longtailvideo.com/player.swf   http://www.longtailvideo.com/support/jw-player-setup-wizard?example=204   LNX%2010,0,32,18   -   -   -   -
2010-03-12   23:51:21   SEA4   192.0.2.222   play   3914   OK   bfd8a98bee0840d9b871b7f6ade9908f   rtmp://shqshne4jdp4b6.cloudfront.net/cfx/st​  key=value   http://player.longtailvideo.com/player.swf   http://www.longtailvideo.com/support/jw-player-setup-wizard?example=204   LNX%2010,0,32,18   myvideo   p=2&q=4   flv   1
2010-03-12   23:53:44   SEA4   192.0.2.4   stop   323914   OK   bfd8a98bee0840d9b871b7f6ade9908f   rtmp://shqshne4jdp4b6.cloudfront.net/cfx/st​  key=value   http://player.longtailvideo.com/player.swf   http://www.longtailvideo.com/support/jw-player-setup-wizard?example=204   LNX%2010,0,32,18   dir/other/myvideo   p=2&q=4   flv   1
2010-03-12   23:53:44   SEA4   192.0.2.103   play   8783724   OK   bfd8a98bee0840d9b871b7f6ade9908f   rtmp://shqshne4jdp4b6.cloudfront.net/cfx/st​  key=value   http://player.longtailvideo.com/player.swf   http://www.longtailvideo.com/support/jw-player-setup-wizard?example=204   LNX%2010,0,32,18   dir/favs/myothervideo   p=42&q=14   mp4   2
2010-03-12   23:56:21   SEA4   192.0.2.199   stop   429822014   OK   bfd8a98bee0840d9b871b7f6ade9908f   rtmp://shqshne4jdp4b6.cloudfront.net/cfx/st​  key=value   http://player.longtailvideo.com/player.swf   http://www.longtailvideo.com/support/jw-player-setup-wizard?example=204   LNX%2010,0,32,18   dir/favs/myothervideo   p=42&q=14   mp4   2
2010-03-12   23:59:44   SEA4   192.0.2.14   disconnect   429824092   OK   bfd8a98bee0840d9b871b7f6ade9908f   rtmp://shqshne4jdp4b6.cloudfront.net/cfx/st​  key=value   http://player.longtailvideo.com/player.swf   http://www.longtailvideo.com/support/jw-player-setup-wizard?example=204   LNX%2010,0,32,18   -   -   -   -	

Access logging is an optional feature of CloudFront. There is no extra charge for enabling access logging. However, you accrue the usual Amazon S3 charges for storing and accessing the files on Amazon S3 (you can delete them at any time).