PutBucketLogging介面用於為bucket開啟訪問日誌記錄功能。

這個功能開啟後,OSS將自動記錄訪問這個bucket請求的詳細資料,並按照用戶指定的規則,以小時為單位,將訪問日誌作為一個Object寫入用戶指定的bucket。OSS提供Bucket訪問日誌的目的是為了方便bucket的擁有者理解和分析bucket的訪問行為。OSS提供的Bucket訪問日誌不保證記錄下每一條訪問記錄。

说明
OSS提供Bucket訪問日誌的目的是為了方便bucket的擁有者理解和分析bucket的訪問行為。OSS提供的Bucket訪問日誌不保證記錄下每一條訪問記錄。

請求文法

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)

表 1. 請求元素
名稱 類型 是否必需 描述
BucketLoggingStatus 容器 訪問日誌狀態資訊的容器

子項目:LoggingEnabled

父元素:無

LoggingEnabled 容器 訪問日誌資訊的容器。這個元素在開啟時需要,關閉時不需要。

子項目:TargetBucket, TargetPrefix

父元素:BucketLoggingStatus

TargetBucket 字元 在開啟訪問日誌的時候必需 指定存放訪問日誌的Bucket。

子項目:無

父元素:BucketLoggingStatus.LoggingEnabled

TargetPrefix 字元 指定最終被保存的訪問記錄檔首碼。類型:子項目:None父元素:BucketLoggingStatus.LoggingEnabled

儲存訪問日誌記錄的object命名規則

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

命名規則中,TargetPrefix由用戶指定;YYYY, mm, DD, HH, MM和SS分別是該Object被建立時的阿拉伯數位年,月,日,小時,分鐘和秒(注意位元);UniqueString為OSS系統生成的字元串。一個實際的用於儲存OSS訪問日誌的Object名稱例子如下:

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

上例中,“MyLog-”是用戶指定的Object首碼;“oss-example”是源bucket的名稱;“2012-09-10-04-00-00”是該Object被建立時的北京時間;“0000” 是OSS系統生成的字元串。

LOG檔案格式

表 2. LOG檔案格式
名稱 例子 含義
Remote IP 119.140.142.11 請求發起的IP地址(Proxy代理或用戶防火牆可能會屏蔽該欄位)
Reserved - 保留欄位
Reserved - 保留欄位
Time [02/May/2012:00:00:04 +0800] OSS收到請求的時間
Request-URI “GET /aliyun-logo.png HTTP/1.1“ 用戶請求的URI(包括query-string)
HTTP Status 200 OSS返回的HTTP狀態碼
SentBytes 5576 用戶從OSS下載的流量
RequestTime (ms) 71 完成本次請求的時間(毫秒)
Referer
http://www.aliyun.com/product/oss
請求的HTTP Referer
User-Agent curl/7.15.5 HTTP的User-Agent頭
HostName oss-example.regionid.example.com 請求訪問網域名稱
Request ID 505B01695037C2AF032593A4 用於唯一標示該請求的UUID
LoggingFlag true 是否開啟了訪問日誌功能
Requester Aliyun ID 1657136103983691 要求者的阿里雲ID;匿名訪問為“-”
Operation GetObject 請求類型
Bucket oss-example 請求訪問的Bucket名字
Key /aliyun-logo.png 用戶請求的Key
ObjectSize 5576 Object大小
Server Cost Time (ms) 17 OSS伺服器處理本次請求所花的時間(毫秒)
Error Code NoSuchBucket OSS返回的錯誤碼
Request Length 302 用戶請求的長度(Byte)
UserID 1657136103983691 Bucket擁有者ID
Delta DataSize 280 Bucket大小的變化量;若沒有變化為“-”
Sync Request - 是否是CDN回源請求;若不是為“-”
Reserved - 保留欄位

細節分析

  • 源Bucket和目標Bucket必須屬於同一個用戶。
  • 上面所示的請求文法中,“BucketName”表示要開啟訪問日誌記錄的bucket;“TargetBucket”表示訪問日誌記錄要存入的bucket;“TargetPrefix”表示儲存訪問日誌記錄的object名字首碼,可以為空。
  • 源bucket和目標bucket可以是同一個Bucket,也可以是不同的Bucket;用戶也可以將多個的源bucket的LOG都保存在同一個目標bucket內(建議指定不同的TargetPrefix)。
  • 當關閉一個Bucket的訪問日誌記錄功能時,只要發送一個空的BucketLoggingStatus即可,具體方法可以參考下面的請求樣本。
  • 所有PUT Bucket Logging請求必須帶簽名,即不支援匿名訪問。
  • 如果PUT Bucket Logging請求發起者不是源bucket(請求樣本中的BucketName)的擁有者,OSS返回403錯誤碼。
  • 如果源bucket不存在,OSS返回錯誤碼:NoSuchBucket。
  • 如果PUT Bucket Logging請求發起者不是目標bucket(請求樣本中的TargetBucket)的擁有者,OSS返回403;如果目標bucket不存在,OSS返回錯誤碼:InvalidTargetBucketForLogging。
  • 源Bucket和目標Bucket必須屬於同一個資料中心,否則返回400錯誤,錯誤碼為:InvalidTargetBucketForLogging。
  • PUT Bucket Logging請求中的XML不合法,返回錯誤碼:MalformedXML。
  • 源bucket和目標bucket可以是同一個Bucket;用戶也可以將不同的源bucket的LOG都保存在同一個目標bucket內(注意要指定不同的TargetPrefix)。
  • 源Bucket被刪除時,對應的Logging規則也將被刪除。
  • OSS以小時為單位生成bucket訪問的Log檔案,但並不表示這個小時的所有請求都記錄在這個小時的LOG檔案內,也有可能出現在上一個或者下一個LOG檔案中。
  • OSS生成的Log檔案命名規則中的“UniqueString”僅僅是OSS為其生成的UUID,用於唯一標識該檔案。
  • OSS生成一個bucket訪問的Log檔案,算作一次PUT操作,並記錄其佔用的空間,但不會記錄產生的流量。LOG生成後,用戶可以按照普通的Object來操作這些LOG檔案。
  • OSS會忽略掉所有以“x-”開頭的query-string參數,但這個query-string會被記錄在訪問LOG中。如果你想從海量的訪問日誌中,標示一個特殊的請求,可以在URL中添加一個“x-”開頭的query-string參數。如:

    http://oss-example.regionid.example.com/aliyun-logo.png

    http://oss-example.regionid.example.com/aliyun-logo.png?x-user=admin

    OSS處理上面兩個請求,結果是一樣的。但是在訪問LOG中,你可以通過搜索“x-user=admin”,很方便地定位出經過標記的這個請求。
  • OSS的LOG中的任何一個欄位,都可能出現“-”,用於表示未知數據或對於當前請求該欄位無效。
  • 根據需求,OSS的LOG格式將來會在尾部添加一些欄位,請開發人員開發Log處理工具時考慮相容性的問題。
  • 如果用戶上傳了Content-MD5要求標頭,OSS會計算body的Content-MD5並檢查一致性,如果不一致,將返回InvalidDigest錯誤碼。

樣本

開啟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 qn6qrrqxo2oawuk53otfjbyc:KU5h8YMUC78M30dXqf3JxrTZHiA=
<?xml version="1.0" encoding="UTF-8"?>
<BucketLoggingStatus>
<LoggingEnabled>
<TargetBucket>doc-log</TargetBucket>
<TargetPrefix>MyLog-</TargetPrefix>
</LoggingEnabled>
</BucketLoggingStatus>

返回樣本:

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

關閉bucket訪問日誌的請求樣本:

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>

返回樣本:

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