Object Storage Service:PutBucketLogging

Usage notes

• The oss:PutBucketLogging permission is required for enabling logging for a bucket by calling the PutBucketLogging operation. For more information, see Attach a custom policy to a RAM user.

• 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: Host
<?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

Response headers

All headers in the response to a PutBucketLogging request are common response headers. For more information, see Common response headers.

Examples

Examples for buckets

• Sample request for enabling logging

  PUT /?logging HTTP/1.1
  Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  Content-Length: 186
  Date: Thu, 17 Apr 2025 03:21:12 GMT
  Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
  
  <?xml version="1.0" encoding="UTF-8"?>
  <BucketLoggingStatus>
      <LoggingEnabled>
          <TargetBucket>examplebucket</TargetBucket>
          <TargetPrefix>MyLog-</TargetPrefix>
          <LoggingRole>AliyunOSSLoggingDefaultRole</LoggingRole>
      </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 for disabling logging

  To disable logging for a bucket, only 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: Thu, 17 Apr 2025 04:21:12 GMT
  Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
  <?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

  Examples for vector buckets

  When specifying the Host for a vector bucket, use the standard Alibaba Cloud region ID (example: cn-hangzhou). Do not use the legacy OSS region ID (example: oss-cn-hangzhou) used for general-purpose buckets.

  Sample request for enabling logging

  PUT /?logging HTTP/1.1
  Host: exampebucket-123***456.cn-hangzhou.oss-vectors.aliyuncs.com
  Content-Length: 186
  Content-Type: application/json
  Date: Thu, 17 Apr 2025 03:21:12 GMT
  Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
  
  {
    "BucketLoggingStatus": {
      "LoggingEnabled": {
        "TargetBucket": "examplebucket",
        "TargetPrefix": "MyLog-",
        "LoggingRole": "AliyunOSSLoggingDefaultRole"
      }
    }
  }

  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

OSS SDKs

Use OSS SDKs for the following programming languages to call the PutBucketLogging operation:

• Java

• Python V2

• PHP V2

• Go V2

• C

• .NET

• Node.js

• Ruby

ossutil

For information about the ossutil command that corresponds to the PutBucketLogging operation, see put-bucket-logging.

Error codes