You can call this operation to enable logging for a bucket. After you enable and configure logging for a bucket, 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 where the generated logs are stored can be the same or different buckets. However, the destination bucket must belong to the same account in the same region as the source bucket.
  • OSS generates bucket access logs on an hourly basis. However, requests in the previous hour may be recorded in the log generated for the subsequent hour.

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

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

    You can configure lifecycle rules to delete log objects at regular intervals. For more information, see Lifecycle rules.

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

Request structure

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
    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 response
    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

    To disable logging for a bucket, you need only to send an empty BucketLoggingStatus. The following code provides an example on how to disable logging:

    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 response
    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

SDK

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.