Enables the access logging function for a bucket. When this function is enabled, OSS automatically records the details about the requests to this bucket, and follows the user-specified rules to write the access logs as an object into a user-specified bucket on an hourly basis.

Note
  • When the source bucket is deleted, the corresponding logging rules are also deleted.
  • OSS generates a bucket access log file every hour. However, all requests during the hour may not be recorded in the log file, but may get recorded in the previous or next log file.
  • Each time OSS generates a bucket access log file, this is considered a PUT operation and the occupied space is recorded, but the generated traffic is not recorded. After log files are generated, you can operate these log files as common objects.
  • OSS ignores all query-string parameters prefixed by “x-“ but such query-string parameters are recorded in access logs. If you want to mark a special request from massive access logs, you can add a query-string parameter prefixed by “x-“ to the URL. For example, you can add mark http://oss-example.regionid.example.com/aliyun-logo.png by adding a parameter prefixed by "x-" as follows: http://oss-example.regionid.example.com/aliyun-logo.png?x-user=admin. The added parameter is ignored. However, you can locate the request by searching "x-user=admin".

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 elements

Note All PutBucketLogging requests must signed because the anonymous access is not supported.
Element Type Required Description
BucketLoggingStatus Container Yes Specifies the container for storing access log status information

Sub-node: LoggingEnabled

Parent node: None
LoggingEnabled Container No Specifies the container for storing access log information. This element is required only when server access logging is enabled.

Sub-node: TargetBucket, TargetPrefix

Parent node: BucketLoggingStatus
TargetBucket String This element is required when server access logging is enabled Specifies the bucket for storing access logs. The source bucket and target bucket can be the same or different buckets. You can save logs from multiple source buckets to the same target bucket (in this case, we recommend that you assign different values to TargetPrefix).

Sub-node: None

Parent node: BucketLoggingStatus.LoggingEnabled
TargetPrefix String No Specifies the prefix of the names of saved access log files, which can be null.

Sub-node: None

Parent node: BucketLoggingStatus.LoggingEnabled

Naming rules for the objects storing access logs

The format of an object name is as follows:

<TargetPrefix><SourceBucket>-YYYY-mm-DD-HH-MM-SS-UniqueString

The following table describes the parameters in an object name:

Parameter Description
TargetPrefix Specifies the prefix of the object name.
YYYY-mm-DD-HH-MM-SS Indicates the time when the object is created. YYYY, mm, DD, HH, MM, and SS indicate the year, month, day, hour, minutes, and seconds individually. For example: 2012-09-10-04-00-00.
UniqueString Indicates the unique UUID generated by OSS to identify a log.

An example object name is as follows:

MyLog-oss-example-2012-09-10-04-00-00-0000

In the preceding example, MyLog- is the prefix specified by the user, oss-example is the name of the source bucket, 2012-09-10-04-00-00 is the time when the object is created, and 0000 is the UUID string generated by OSS.

Log file format

Note
  • You may see “-“ in any field of OSS logs. It indicates that data is unknown or the field is invalid for the current request.
  • Certain fields are added to the end of OSS log files in future based on the requirements. We recommend that developers consider compatibility issues when developing log processing tools.
Parameter Example Description
Remote IP 119.xxx.xx.11 The IP address from which the request is initiated. The proxy or user firewall may block this field.
Reserved - The reserved field.
Reserved - The reserved field.
Time [02/May/2012:00:00:04 +0800] The time when OSS received the request.
Request-URI "GET /aliyun-logo.png HTTP/1.1" The URI of the user request, including query-string.
HTTP Status 200 The HTTP status code returned by OSS.
SentBytes 5576 The amount of data downloaded from OSS by the user, in bytes.
RequestTime (ms) 71 The length of time used to complete the request, in milliseconds.
Referer http://www.aliyun.com/product/oss The HTTP Referer of the request.
User-Agent curl/7.15.5 The User-Agent field in the HTTP header.
HostName oss-example.oss-cn-hangzhou.aliyuncs.com The domain name to access.
Request ID 505B016950xxxxxx032593A4 The UUID used to identify the request.
LoggingFlag true Indicates whether logging is enabled.
Requester Aliyun ID 16571xxxxxx83691 The RAM user ID. This value is a hyphen (-) for access from anonymous users.
Operation GetObject The type of the request that is sent to perform operations on the object or bucket.
Bucket oss-example The name of the bucket to access.
Key /aliyun-logo.png The name of the object requested by the user.
ObjectSize 5576 The size of the object.
Server Cost Time (ms) 17 The length of time for the OSS server to process this request, in milliseconds.
Error Code NoSuchBucket The error code returned by OSS.
Request Length 302 The length of the user request, in bytes.
UserID 16571xxxxxx83691 The ID of the bucket owner.
Delta DataSize 280 The change to the bucket size. The value is a hyphen (-) if there are no changes to the bucket size.
Sync Request - Indicates whether the request is a CDN back-to-origin request. The value is a hyphen (-) if the request is not a back-to-origin request.
StorageClass Standard The storage class of the current object. Valid values: Standard/IA/Archive/-. The value is a hyphen (-) if the storage class information cannot be obtained or the target object is a bucket.
TargetStorageClass Standard The destination storage class to which the object is converted after a lifecycle rule is triggered or CopyObject is called for the object. Valid values: Standard/IA/Archive/-. The value is a hyphen (-) if the storage class information about the destination object cannot be obtained or the storage class fails to be converted by using a lifecycle rule or by calling CopyObject.

Examples

Example of a request for enabling bucket access 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 qn6qrrqxo2oawuk53otfjbyc:KU5h8YMUC78M30dXqf3JxrTZHiA=
<? xml version="1.0" encoding="UTF-8"? >
<BucketLoggingStatus>
<LoggingEnabled>
<TargetBucket>doc-log</TargetBucket>
<TargetPrefix>MyLog-</TargetPrefix>
</LoggingEnabled>
</BucketLoggingStatus>

Response example:

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906008B
Date: Fri, 04 May 2012 03:21:12 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS

Example of a request for disabling bucket access 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 qn6qrrqxo2oawuk53otfjbyc:KU5h8YMUC78M30dXqf3JxrTZHiA=
<? xml version="1.0" encoding="UTF-8"? >
<BucketLoggingStatus>
</BucketLoggingStatus>

Response example:

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906008B
Date: Fri, 04 May 2012 04:21:12 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS

SDK

The SDKs of this API are as follows:

Error codes

Error code HTTP status code Description
NoSuchBucket 404 The source bucket does not exist. The source bucket and the target bucket must be owned by the same user.
InvalidTargetBucketForLogging 400 The source bucket and the target bucket are in different regions.
InvalidDigest 400 If you include the Content-MD5 header in the request, OSS calculates the Content-MD5 of the request body and checks if the two are the same. If the two values are different, this error is returned.
MalformedXML 400 The XML file in the request is invalid.
InvalidTargetBucketForLogging 403 The user who initiates the request is not the owner of the target bucket.
AccessDenied 403 The user who initiates the request is not the owner of the source bucket,