Configuring Logging for a Bucket

Functions

When a bucket is created, the logging function is not enabled by default. To generate logs recording operations on buckets, you need to enable the logging function for the bucket. After the logging function is enabled, a log is generated for each operation on a bucket and multiple logs are packed into a log file. When enabling the logging function, you need to specify a location where log files are stored. They can be stored in the bucket for which the logging is enabled, or in other buckets that you have the required permissions. However, the bucket where log files are stored and the bucket for which the logging is enabled must be in the same region.

Log files are generated by OBS and uploaded to the bucket where logs are stored. Therefore, OBS needs to be authorized to upload generated log files. Before configuring the logging function, you need to create an agency for OBS in IAM, the agency name is configured as a parameter of the bucket, and the logging function must be configured under the LoggingEnabled tag in the XML file. You only need to authorize the agency with the upload permissions for the target bucket.

Example of agency permissions

{
    "Version": "1.1",
    "Statement": [
        {
            "Action": [
                "obs:object:PutObject"
            ],
            "Resource": [
                "OBS:*:*:object:mybucketlogs/*"
            ],
            "Effect": "Allow"
        }
    ]
}

To disable the bucket logging function, upload a logging file with an empty BucketLoggingStatus tag.

By default, a bucket whose storage class is Warm or Cold cannot be used for storing log files. Stored log files occupy storage space in a bucket. Therefore, users are charged for the logging service based on the pricing for data storage.

If the target bucket has KMS encryption enabled, grant the agency access to KMS.

Request Syntax

    
     
       
       
         PUT /?logging HTTP/1.1 
Host: bucketname.obs.region.example.com
Date: date
Authorization: signatureValue
<?xml version="1.0" encoding="UTF-8"?>
<BucketLoggingStatus>
  <Agency>agency-name</Agency>
  <LoggingEnabled>
    <TargetBucket>mybucketlogs</TargetBucket>
    <TargetPrefix>mybucket-access_log-/</TargetPrefix>
    <TargetGrants>
      <Grant>
        <Grantee>
          <ID>domainID</ID>
        </Grantee>
        <Permission>READ</Permission>
      </Grant>
    </TargetGrants>
  </LoggingEnabled>
</BucketLoggingStatus>

        

      

    
   

Request Parameters

This request contains no message parameters.

Request Headers

This request uses common headers. For details, see Table 3.

Request Elements

**Table 1** Request elements
Element	Description	Mandatory
BucketLoggingStatus	Container for logging status information Type: container	Yes
Agency	Name of the IAM agency created by the owner of the target bucket on IAM. Type: string	You must set this parameter when enabling the logging function. Do not set this parameter when disabling the logging function.
LoggingEnabled	Container for logging information. Present this element when enabling the logging function. Otherwise, absent it. You can add specific logging information in this element. Type: container	You must set this parameter when enabling the logging function. Do not set this parameter when disabling the logging function.
Grant	Container for the grantee and the grantee's logging permissions. It describes who has the permission to access the generated log files. Type: container	No
Grantee	Container for the user that is granted with the logging permission. Type: container	No
ID	Account ID of the authorized user, which is globally unique. Type: string	No
Permission	Permissions of the grantee to the generated logs. Type: string Value options: FULL_CONTROL, READ, WRITE	No
TargetBucket	When enabling the logging function, the owner of the bucket being logged can specify a target bucket to store the generated log files. Ensure that the bucket owner who configures the logging function has the FULL_CONTROL permission for the bucket that stores log files. Log files generated for multiple buckets can be stored in the same target bucket. If you do so, you need to specify different TargetPrefixes to classify logs for different buckets. Type: string	You must set this parameter when enabling the logging function. Do not set this parameter when disabling the logging function.
TargetPrefix	You can specify a prefix using this element so that log files are named with this prefix. Type: string	You must set this parameter when enabling the logging function. Do not set this parameter when disabling the logging function.
TargetGrants	Container for granting information. Type: container	No

Naming rules for access logs

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

<TargetPrefix> is the log name prefix specified by the user.
YYYY-mm-DD-HH-MM-SS indicates the date and time when the log is generated.
<UniqueString> indicates a character string generated by OBS.

The following is an example of a log file name:

    
         bucket-log2015-06-29-12-22-07-N7MXLAF1BDG7MPDV

bucket-log is the target prefix specified by the user.
2015-06-29-12-22-07 indicates the time when the log is generated.
N7MXLAF1BDG7MPDV is a string automatically generated by OBS

Format of bucket access logs

The following shows an access log delivered to the target bucket:

    
         787f2f92b20943998a4fe2ab75eb09b8 bucket [13/Aug/2015:01:43:42 +0000] xx.xx.xx.xx 787f2f92b20943998a4fe2ab75eb09b8 281599BACAD9376ECE141B842B94535B  REST.GET.BUCKET.LOCATION - "GET /bucket?location HTTP/1.1" 200 - 211 - 6 6 "-"  "HttpClient" - -

Each access log contains the following information:

**Table 2** Format of bucket access logs
Parameter	Example	Description
BucketOwner	787f2f92b20943998a4fe2ab75eb09b8	ID of the bucket owner
Bucket	bucket	Bucket name
Time	[13/Aug/2015:14:43:42 +0000]	Request timestamp in the [dd/MMM/yyyy:HH:mm:ss Z] format
Remote IP	xx.xx.xx.xx	Request IP address
Requester	787f2f92b20943998a4fe2ab75eb09b8	ID of the requester When an account initiates a request, this parameter value is the account ID. When an IAM user initiates a request, this parameter value is the ID of the account where the IAM user belongs. When an anonymous user initiates a request, this parameter value is Anonymous.
RequestID	281599BACAD9376ECE141B842B94535B	Request ID
Operation	REST.GET.BUCKET.LOCATION	Operation
Key	-	Object name
Request-URI	GET /bucket?location HTTP/1.1	Request URI
HTTPStatus	200	Response code
ErrorCode	-	Error code
BytesSent	211	Size of the HTTP response, expressed in bytes
ObjectSize	-	Object size
TotalTime	6	Processing time on the server Unit: ms
Turn-AroundTime	6	Total request processing time Unit: ms
Referer	-	Referer header of the request
User-Agent	HttpClient	User-Agent header of the request
VersionID	-	Version ID contained in a request
STSLogUrn	-	Federated authentication and agency information
StorageClass	STANDARD_IA	Current object storage class
TargetStorageClass	GLACIER	Storage class that the object will be transitioned to
DentryName	12456%2Ffile.txt	For a parallel file system, this field represents an internal identifier of a file or directory. Its value consists of a parent directory's inode number and a file or directory name and is displayed in the URL-encoded format. For a bucket, the value of this field is -.

Response Syntax

    
         HTTP/1.1 status_code
Date: date
Content-Length: length

Response Headers

The response to the request uses common headers. For details, see Table 1.

Response Elements

This response contains no elements.

Error Responses

No special error responses are returned. For details about error responses, see Table 2.

Sample Request

    
     
       
       
         PUT /?logging HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 02:40:06 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:mCOjER/L4ZZUY9qr6AOnkEiwvVk=
Content-Length: 528

<?xml version="1.0" encoding="UTF-8"?>
<BucketLoggingStatus>
  <Agency>agencyGrantPutLogging</Agency>
  <LoggingEnabled>
    <TargetBucket>log-bucket</TargetBucket>
    <TargetPrefix>mybucket-access_log-/</TargetPrefix>
    <TargetGrants>
      <Grant>
        <Grantee>
          <ID>783fc6652cf246c096ea836694f71855</ID>
        </Grantee>
        <Permission>READ</Permission>
      </Grant>
    </TargetGrants>
  </LoggingEnabled>
</BucketLoggingStatus>

        

      

    
   

Sample Response

    
         HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BF26000001643663CE53B6AF31C619FD
x-obs-id-2: 32AAAQAAEAABSAAkpAIAABAAAQAAEAABCT9CjuOx8cETSRbqkm35s1dL/tLhRNdZ
Date: WED, 01 Jul 2015 02:40:06 GMT
Content-Length: 0