Enables logging for a bucket. After you enable and configure logging for a bucket, Object Storage Service (OSS) generates log objects based on a predefined naming convention. This way, access logs are generated and stored in the specified bucket on an hourly basis.

Usage notes

  • The source bucket for which logs are generated and the destination bucket in which the logs are stored can be the same or different. However, the destination bucket must belong to the same Alibaba Cloud account in the same region as the source bucket.
  • OSS generates bucket access logs on an hourly basis. However, requests in an hour may be recorded in the log generated for the previous or subsequent hour.

    For more information about the naming conventions of log objects and log format, see Logging.

  • Before you disable logging, OSS keeps generating log objects. Delete log objects that you no longer need to reduce your storage costs.

    You can configure lifecycle rules to regularly delete log objects. For more information, see Lifecycle rules based on the last modified time.

  • More fields may be added to OSS logs. We recommend that developers consider potential compatibility issues when they develop log processing tools.

Request syntax

PUT /?logging HTTP/1.1
Date: GMT Date
Content-Length: ContentLength
Content-Type: application/xml
Authorization: SignatureValue 
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
<?xml version="1.0" encoding="UTF-8"?>
<BucketLoggingStatus>
    <LoggingEnabled>
        <TargetBucket>TargetBucket</TargetBucket>
        <TargetPrefix>TargetPrefix</TargetPrefix>
    </LoggingEnabled>
</BucketLoggingStatus>

Request headers

A PutBucketLogging request contains only common request headers. For more information, see Common request headers.

Request elements

Element Type Required Example Description
BucketLoggingStatus Container Yes N/A The container that stores the logging status information.

Child nodes: LoggingEnabled

Parent nodes: none

LoggingEnabled Container This parameter is required when you enable logging. N/A The container that stores the access log information.

Child nodes: TargetBucket and TargetPrefix

Parent nodes: BucketLoggingStatus

TargetBucket String This parameter is required when you enable logging. examplebucket The bucket that stores access logs.

Child nodes: none

Parent nodes: BucketLoggingStatus and LoggingEnabled

TargetPrefix String No MyLog- The prefix of the saved log objects. This element can be left empty.

Child nodes: none

Parent nodes: BucketLoggingStatus and LoggingEnabled

Response headers

The response to a PutBucketLogging request contains only common response headers. For more information, see Common response headers.

Examples

  • Sample request on how to enable logging for a bucket
    PUT /?logging HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Content-Length: 186
    Date: Fri, 04 May 2012 03:21:12 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otf****:KU5h8YMUC78M30dXqf3JxrTZ****
    <?xml version="1.0" encoding="UTF-8"?>
    <BucketLoggingStatus>
    <LoggingEnabled>
    <TargetBucket>examplebucket</TargetBucket>
    <TargetPrefix>MyLog-</TargetPrefix>
    </LoggingEnabled>
    </BucketLoggingStatus>
    Sample responses
    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674E888648906008B
    Date: Fri, 04 May 2012 03:21:12 GMT
    Content-Length: 0
    Connection: keep-alive
    Server: AliyunOSS
  • Sample request on how to disable logging for a bucket

    To disable logging for a bucket, you need only to send an empty BucketLoggingStatus. Example:

    PUT /?logging HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Content-Type: application/xml
    Content-Length: 86
    Date: Fri, 04 May 2012 04:21:12 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otf****:KU5h8YMUC78M30dXqf3JxrTZ****
    <?xml version="1.0" encoding="UTF-8"?>
    <BucketLoggingStatus>
    </BucketLoggingStatus>
    Sample responses
    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674125A4D8906008B
    Date: Fri, 04 May 2012 04:21:12 GMT
    Content-Length: 0
    Connection: keep-alive
    Server: AliyunOSS

SDKs

You can use OSS SDKs for the following programming languages to call the PutBucketLogging operation:

Error codes

Error code HTTP status code Description
NoSuchBucket 404 The error message returned because the source bucket does not exist.
InvalidTargetBucketForLogging 400 The error message returned because the source bucket and the destination bucket do not belong to the same data center.
InvalidDigest 400 The error message returned because the Content-MD5 value of the message body is inconsistent with the Content-MD5 value of the request header.
MalformedXML 400 The error message returned because the XML format in the request is invalid.
InvalidTargetBucketForLogging 403 The error message returned because the requester is not the owner of the destination bucket.
AccessDenied 403 The error message returned because the requester is not the owner of the source bucket.