Server Access Logging Configuration API

Amazon Simple Storage Service: 2006-03-01

previous page next page

Server Access Logging Configuration API

[Important]Important

This section describes Beta functionality that is subject to change in future releases. Please provide feedback on this functionality in the

Amazon S3 Developer Forum.

Each Amazon S3 bucket has an associated XML sub-resource that you can read and write in order to inspect or change the logging status for that bucket. The XML schema for the bucket logging status resource is common across SOAP and REST.

The BucketLoggingStatus element has the following structure.

Example 

<?xml version="1.0" encoding="UTF-8"?>
<BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01">
    <LoggingEnabled>
        <TargetBucket>mylogs</TargetBucket>
        <TargetPrefix>access_log-</TargetPrefix>
        <TargetGrants>
	    <Grant>
	        <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AmazonCustomerByEmail">
	            <EmailAddress>email_address</EmailAddress>
	        </Grantee>
	        <Permission>permission</Permission>
	    </Grant>
        </TargetGrants>
    </LoggingEnabled>
</BucketLoggingStatus>

Following is a list of elements that belong to the BucketLoggingStatus element.

  • LoggingEnabled

    The presence of this element indicates that server access logging is enabled for the bucket. The absence of this element (and all nested elements) indicates that logging is disabled for the bucket.

  • TargetBucket

    This element specifies the bucket where server access logs will be delivered. You can have your logs delivered to any bucket that you own, including the same bucket that is being logged. You can also configure multiple buckets to deliver their logs to the same target bucket. In this case you should choose a different TargetPrefix for each source bucket so that the delivered log files can be distinguished by key.

    [Note] Note

    The source and the target buckets must be in the same location. For more information about bucket location constraints, see How to Select a Region for Your Buckets

  • TargetPrefix

    This element lets you specify a prefix for the keys that the delivered log files will be stored under. For information on how the key name for log files is constructed, see Delivery of Server Access Logs.

  • TargetGrants

    The bucket owner is automatically granted FULL_CONTROL to all logs delivered to the bucket. This optional element enables you grant access to others. Any specified TargetGrants are added to the default ACL. For more information about ACLs, see Access Control Lists.

To enable server access logging, Set or PUT a BucketLoggingStatus with a nested LoggingEnabled element. To disable server access logging, Set or PUT an empty BucketLoggingStatus element.

In REST, the address of the BucketLoggingStatus resource for a bucket 'mybucket' is http://s3.amazonaws.com/mybucket?logging. The PUT and GET methods are valid for this resource. For example, the following request fetches the BucketLoggingStatus resource for mybucket. 

GET ?logging HTTP/1.1
Host: mybucket.s3.amazonaws.com
Date: Wed, 01 Mar  2006 12:00:00 GMT
Authorization: AWS YOUR_AWS_ACCESS_KEY_ID:YOUR_SIGNATURE_HERE

HTTP/1.1 200 OK
Date: Wed, 01 Mar  2006 12:00:00 GMT
Connection: close
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>
<BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01">
  <LoggingEnabled>
    <TargetBucket>mybucketlogs</TargetBucket>
    <TargetPrefix>mybucket-access_log-/</TargetPrefix>
        <TargetGrants>
	    <Grant>
	        <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AmazonCustomerByEmail">
	            <EmailAddress>[email protected]</EmailAddress>
	        </Grantee>
	        <Permission>READ</Permission>
	    </Grant>
        </TargetGrants>
    
  </LoggingEnabled>
</BucketLoggingStatus>

In SOAP, you can work with BucketLoggingStatus resource using the SOAPSetBucketLoggingStatus and SOAPGetBucketLoggingStatus operations.

Amazon S3 checks the validity of the proposed BucketLoggingStatus when you try to Set or PUT to it. If the TargetBucket does not exist, is not owned by you, or does not have the appropriate grants, you will receive the InvalidTargetBucketForLogging error. If your proposed BucketLoggingStatus document is not well-formed XML or does not match our published schema, you will receive the MalformedXMLError.

BucketLoggingStatus Changes Take Effect Over Time

Changes to the logging status for a bucket are visible in the configuration API immediately, but they take time to actually affect the delivery of log files. For example, if you enable logging for a bucket, some requests made in the following hour might be logged, while others might not. Or, if you change the target bucket for logging from bucket A to bucket B, some logs for the next hour might continue to be delivered to bucket A, while others might be delivered to the new target bucket B. In all cases, the new settings will eventually take effect without any further action on your part.

previous page start next page