# 设置桶日志管理配置-SetBucketLogging #### 功能介绍 用户在创建或访问桶时，默认是不生成桶日志的。用户可通过打开日志配置管理开关，开启桶日志功能。OBS会为您记录跟桶操作相关的各种请求日志，产生的桶日志记录会被存储至同账号同区域下的同一个桶或其他桶中，便于您通过检索和分析日志来完成异常事件回溯和定位等工作。了解更多有关桶日志信息，请参见[配置桶的日志记录](https://support.huaweicloud.com/usermanual-obs/obs_03_0329.html)。 #### 接口约束 - 日志可以存储在产生日志的源桶，也可以存储在其他桶，但日志存储桶和源桶必须属于同一账号下的相同区域。 将源桶产生的日志文件存储至日志存储桶，该操作本身也会生成新的日志，此时如果源桶和日志存储桶是同一个，则存储日志操作生成的日志会再次被存储，导致日志不断循环产生。因此，建议您将源桶和日志存储桶配置为不同的桶。 - 默认存储类别为低频访问存储或归档存储的桶不能作为存放日志文件的桶。日志文件存放到桶中后，这些日志文件会占用空间，并按照用户存放数据同样的计费策略进行计费。 #### 授权信息 **调用接口需要的授权** 您必须是桶拥有者或拥有设置桶日志管理配置的权限，才能调用本接口，建议使用IAM或桶策略进行授权。了解更多OBS授权方式请参见[OBS不同权限控制方式的区别](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0001.html)。 - 如果使用**IAM授权** ，那么请在"角色与策略授权"、"身份策略授权"两种IAM授权方式中选择一种，并配置相应权限： - 如果使用**角色与策略授权** （旧版IAM，即IAM v3接口），需具备**obs:bucket:PutBucketLogging** 权限，授权操作请参见[创建IAM自定义策略](https://support.huaweicloud.com/usermanual-iam/iam_01_0605.html)。 - 如果使用**身份策略授权** （新版IAM，即IAM v5接口），如下表所示，需具备**obs:bucket:putBucketLogging** 权限，授权操作请参见[创建IAM自定义身份策略](https://support.huaweicloud.com/usermanual-iam5/iam_01_0917.html)。 | 授权项 Action | 访问级别 Access Level | 资源类型（\*为必须） Resource Type (\*: required) | [条件键](https://support.huaweicloud.com/api-obs/obs_04_0112.html#ZH-CN_TOPIC_0000002375307974__condition_table) Condition Key | [别名](https://support.huaweicloud.com/iam5_faq/iam_01_1103.html) Alias | 依赖的授权项 Dependencies | |:---|:---|:---|:---|:---|:---| | obs:bucket:putBucketLogging | Write | bucket \* | - [g:EnterpriseProjectId](https://support.huaweicloud.com/usermanual-iam5/iam_01_0934.html#section2) - [g:ResourceTag/\](https://support.huaweicloud.com/usermanual-iam5/iam_01_0934.html#section2) | - | - | | obs:bucket:putBucketLogging | Write | - | - obs:EpochTime - obs:SourceIp - obs:TlsVersion - obs:CustomDomain | - | - | - 如果使用**桶策略** 进行授权，需具备**obs:bucket:PutBucketLogging** 权限，具体操作请参见[自定义创建桶策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0123.html)。 #### URI PUT / #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-obs/obs_04_0006.html)。调用前需要先[计算API签名](https://support.huaweicloud.com/api-obs/obs_04_0009.html)，并将签名添加到请求中。 您还可以使用[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/OBS/doc?api=SetBucketLogging)在线调试接口。 #### 请求消息样式 以下为请求消息样例，请将示例中的*BucketName* 修改为您的桶名，*RegionID* 修改为桶所在的区域ID，可参考[支持区域](https://console.huaweicloud.com/apiexplorer/#/endpoint/OBS)获取区域ID。 ``` PUT /?logging HTTP/1.1 Host: BucketName.obs.RegionID.myhuaweicloud.com Date: GMT Date Authorization: SignatureValue agency-name mybucketlogs mybucket-access_log-/ DAY domainID READ ``` #### URI参数（URI Parameters） 表1URI参数 | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | logging | String | 否 | **参数解释**： 用于标识API接口与桶日志有关。 **约束限制**： 无。 **取值范围**： logging **默认取值**： 不涉及 | #### 请求头参数（Request headers） 该请求使用公共请求头，具体参见[表3](https://support.huaweicloud.com/api-obs/obs_04_0007.html#ZH-CN_TOPIC_0136436606__table25197309)。 #### 请求体参数（Request body） 表2请求体参数 | 元素名字 | 元素类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | BucketLoggingStatus | Container | 是 | **参数解释：** 日志状态信息的容器。当BucketLoggingStatus为空时，桶日志功能关闭。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | Agency | String | 当设置logging时，必选； 当关闭logging时，勿选。 | **参数解释：** 目标桶Owner通过统一身份认证服务创建的对OBS服务的委托的名称。创建委托详见[创建委托](https://support.huaweicloud.com/api-iam/iam_12_0003.html)。 **约束限制：** 委托必须为"对象存储服务 OBS"的云服务委托，被委托方必须包含**obs:bucket:PutBucketLogging**权限。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | LoggingEnabled | Container | 当设置logging时，必选； 当关闭logging时，勿选。 | **参数解释：** 该元素起到对日志配置管理的使能作用（呈现此元素则打开日志配置，否则关闭配置）。在此元素下，可加入具体的日志配置信息。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | Grant | Container | 否 | **参数解释：** 是被授权者及其权限的容器。用于描述谁有什么权限来访问产生的日志文件。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | Grantee | Container | 否 | **参数解释：** 作为被授权logging权限用户的容器。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | ID | String | 否 | **参数解释：** 被授权者的租户ID，全局唯一标识。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | Permission | String | 否 | **参数解释：** 产生的日志文件对被授权者的具体权限。 **约束限制：** 不涉及 **取值范围：** - READ：允许被授权者获取桶内对象列表和桶元数据。 - WRITE：允许被授权者向桶中上传对象。对于桶中现有对象，允许被授权者删除和覆盖这些对象。 - FULL_CONTROL：允许被授予者拥有完全读取、写入、删除桶中对象。 **默认取值：** 不涉及 | | TargetBucket | String | 当设置logging时，必选； 当关闭logging时，勿选。 | **参数解释：** 配置的日志桶的桶名。在生成日志时，配置日志桶的所有者可以指定一个桶用于存放产生的日志文件。 **约束限制：** - 保证配置日志文件的桶owner对存放日志文件的桶有FULL_CONTROL权限。 - 多个桶生成的日志放在同一个目标桶中时，需要指定不同的TargetPrefix以达到为来自不同源桶的日志分类的目的。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | TargetPrefix | String | 当设置logging时，必选； 当关闭logging时，勿选。 | **参数解释：** 通过该元素指定一个前缀，所有生成的日志对象的对象名都以此元素的内容为前缀。 **约束限制：** 不涉及。 **取值范围：** 不超过254个字节。 **默认取值：** 不涉及。 | | TargetSorting | String | 否 | **参数解释：** 配置桶日志归类时指定，按照指定的类型进行日志归类。 **约束限制：** 不涉及。 **取值范围：** DAY：按天分类。 HOUR：按小时分类。 **默认取值：** 不涉及。 | | TargetGrants | Container | 否 | **参数解释：** 授权信息的容器。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | #### 存储访问日志的object命名规则 ``` YYYY-mm-DD-HH-MM-SS- ``` - \为用户指定的目标前缀。TargetPrefix对应请求体中的TargetPrefix元素。 - 如果***\*** 以"**/** "结尾，则在控制台上看到桶生成的日志文件，将统一被存放在目标桶中的以***\*** 命名的文件夹中，日志文件名称为"**YYYY-mm-DD-HH-MM-SS-*\*** "。而实际上OBS没有文件夹的概念，为了方便用户管理数据，OBS通过在对象的名称中增加"/"的方式来模拟文件夹，因此通过API看到桶生成的日志文件名称仍然为"***\* YYYY-mm-DD-HH-MM-SS-*\*** "。 一个实际用于存储OBS访问日志的object名称示例如下： ``` bucket-log/2015-06-29-12-22-07-N7MXLAF1BDG7MPDV ``` - "**bucket-log/**"为用户指定的目标前缀。 - "2015-06-29-12-22-07"为日志生成的日期与时间。 - "N7MXLAF1BDG7MPDV"为OBS自动生成的字符串。 - 如果***\*** 不以"**/** "结尾，则在控制台上看到桶生成的日志文件，将直接被存储在目标桶的根目录下，日志文件名称为"***\*** **YYYY-mm-DD-HH-MM-SS-** ***\*** "。此时通过API看到桶生成的日志文件名称仍然为"***\* YYYY-mm-DD-HH-MM-SS-*\*** "。 一个实际用于存储OBS访问日志的object名称示例如下： ``` bucket-log2015-06-29-12-22-07-N7MXLAF1BDG7MPDV ``` - "**bucket-log**"为用户指定的目标前缀。 - "2015-06-29-12-22-07"为日志生成的日期与时间。 - "N7MXLAF1BDG7MPDV"为OBS自动生成的字符串。 - YYYY-mm-DD-HH-MM-SS为日志生成的日期与时间，各字段依次表示年、月、日、时、分、秒。 - \为OBS自动生成的字符串。 #### 桶访问日志格式 以下所示为在目标桶生成的桶访问日志文件记录：字段间使用空格分隔，包含空格的字段用双引号包裹。 ``` 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" - - ``` 每个桶访问日志都包含如下信息： 表3Bucket Logging格式 | 参数名称 | 参数类型 | 含义 | |:---|:---|:---| | BucketOwner | String | **参数解释：** 桶的ownerId。 示例：787f2f92b20943998a4fe2ab75eb09b8 **取值范围：** 租户id：获取方式请参考[获取账号、IAM用户、项目、用户组、区域、委托的名称和ID](https://support.huaweicloud.com/api-obs/obs_04_0117.html)。 | | Bucket | String | **参数解释：** 桶名。 示例：bucket。 **取值范围：** 桶名命名规则请参考[桶命名规则](https://support.huaweicloud.com/usermanual-obs/zh-cn_topic_0045829088.html#section2)。 | | Time | String | **参数解释：** 请求时间戳。格式为：\[dd/MMM/yyyy:HH:mm:ss Z\]，即 \[日/月/年:小时:分钟:秒 时区\]。 示例： \[13/Aug/2015:14:43:42 +0000\] **取值范围：** 格式为：\[dd/MMM/yyyy:HH:mm:ss Z\]，即 \[日/月/年:小时:分钟:秒 时区\]。 | | Remote IP | String | **参数解释：** 请求IP。 示例： xx.xx.xx.xx **取值范围：** IPv4 0.0.0.0 到 255.255.255.255 IPv6 :: 到 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff | | Requester | String | **参数解释：** 请求者ID。 - 当使用账号或IAM用户发起请求时，此ID为请求者所属账号的账号ID。 - 当使用匿名用户发起请求时，取值为Anonymous。 示例： 787f2f92b20943998a4fe2ab75eb09b8 **取值范围：** 租户id：获取方式请参考[获取账号、IAM用户、项目、用户组、区域、委托的名称和ID](https://support.huaweicloud.com/api-obs/obs_04_0117.html)。 匿名用户：Anonymous。 | | RequestID | String | **参数解释：** 请求ID。 示例： 281599BACAD9376ECE141B842B94535B **取值范围：** 通常为32位数字+字母组成的字符串。 | | Operation | String | **参数解释：** 操作名称。 示例： REST.GET.BUCKET.LOCATION **取值范围：** OBS所有接口。 | | Key | String | **参数解释：** 对象名。 示例： - **取值范围：** 对象名取值参考[对象键命名指导原则](https://support.huaweicloud.com/usermanual-obs/obs_41_0015.html#section0)。 | | Request-URI | String | **参数解释：** 请求URI。由**Http方法 + 资源路径 + query参数 + 协议版本**组成。 示例： GET /bucket?location HTTP/1.1 **取值范围：** 不涉及。 | | HTTPStatus | Integer | **参数解释：** 返回码。 示例： 200 **取值范围：** 常见返回码：\[100, 599\]。 | | ErrorCode | String | **参数解释：** 错误码。 示例： - **取值范围：** 请求的详细错误码。 | | BytesSent | Integer | **参数解释：** HTTP响应的字节大小。 示例： 211 **取值范围：** \[0, \~) 根据实际的响应体决定。 | | ObjectSize | Integer | **参数解释：** 对象大小。 示例： - **取值范围：** 对象大小，不大于48TB。 | | TotalTime | Integer | **参数解释：** 服务端处理时间。单位：ms 示例： 6 **取值范围：** \[0, \~)，根据实际处理时间决定。 | | Turn-AroundTime | Integer | **参数解释：** 总请求时间。 单位：ms 示例： 6 **取值范围：** \[0, \~)，根据实际处理时间决定。 | | Referer | String | **参数解释：** 请求的referrer头域。 示例： - **取值范围：** 请求头域中携带的来源网站地址，根据实际携带决定。 | | User-Agent | String | **参数解释：** 请求的user-agent头域。 示例： HttpClient **取值范围：** 请求头域中携带的客户端标识，根据实际携带决定。 | | VersionID | String | **参数解释：** 请求中带的versionId。 示例： - **取值范围：** - 如果桶开启了多版本，则记录对象的实际版本ID。 - 如果桶未开启多版本，记录默认值"-"。 | | STSLogUrn | String | **参数解释：** 联邦认证及委托授权信息。 示例： - **取值范围：** 请求者委托信息：获取方式请参考[获取账号、IAM用户、项目、用户组、区域、委托的名称和ID](https://support.huaweicloud.com/api-obs/obs_04_0117.html)。 | | StorageClass | String | **参数解释：** 当前的对象存储类型。 - STANDARD：标准存储 - STANDARD_IA：即"WARM"，低频访问存储 - COLD：归档存储 - DEEP_ARCHIVE：深度归档存储 示例： STANDARD_IA **取值范围：** - STANDARD：标准存储 - STANDARD_IA：即"WARM"，低频访问存储 - COLD：归档存储 - DEEP_ARCHIVE：深度归档存储 | | TargetStorageClass | String | **参数解释：** 通过转换后的对象存储类型。 示例： GLACIER **取值范围：** 仅在生命周期存储类型转换场景下有，取值： - STANDARD：标准存储 - STANDARD_IA：即"WARM"，低频访问存储 - COLD：归档存储 - DEEP_ARCHIVE：深度归档存储 | | DentryName | String | **参数解释：** - 对于并行文件系统，是文件/目录的内部标识，由父目录inode编号与文件/目录名称组成，此字段最终呈现为经过URL编码后的格式。 示例：12456%2Ffile.txt - 对于对象桶，该字段为"-"。 **取值范围：** - 并行文件系统：URL编码后的文件/目录的内部标识。 - 对象桶：该字段为默认值"-"。 | | IAMUserId | String | **参数解释：** IAM用户ID。 当使用匿名用户发起请求，记为Anonymous。 示例： 8f3b8c53d29244a780084f2b8c106c32 **取值范围：** - 请求者的用户ID：获取方式请参考[获取账号、IAM用户、项目、用户组、区域、委托的名称和ID](https://support.huaweicloud.com/api-obs/obs_04_0117.html)。 - 匿名用户：Anonymous | | AccessKeyID | String | **参数解释：** 请求者的AccessKey ID。取值-表示匿名请求。 示例： UDSIAMSTUBTEST002852 **取值范围：** 请求者的AccessKey ID。匿名请求该字段为"-"。 | #### 响应消息样式 ``` HTTP/1.1 status_code Date: date Content-Length: length ``` #### 响应头 (Response Headers) 该请求的响应消息使用公共响应头，具体请参考[表1](https://support.huaweicloud.com/api-obs/obs_04_0013.html#ZH-CN_TOPIC_0173612084__d0e686)。 #### 响应体 (Response Body) 本接口的响应消息中不携带响应体。 #### 错误响应消息 无特殊错误，所有错误已包含在[错误码概述](https://support.huaweicloud.com/api-obs/obs_04_0115.html)中。 #### 请求示例 ``` PUT /?logging HTTP/1.1 User-Agent: curl/7.29.0 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Accept: */* Date: Wed, 01 Jul 2015 02:40:06 GMT Authorization: OBS H4IPJX0TQTHTHEBQQCEC:mCOjER/L4ZZUY9qr6AOnkEiwvVk= Content-Length: 528 agencyGrantPutLogging log-bucket mybucket-access_log-/ DAY 783fc6652cf246c096ea836694f71855 READ ``` #### 响应示例 ``` 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 ``` #### 请求示例：关闭桶日志转存 ``` PUT /?logging HTTP/1.1 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:iqSPeUBl66PwXDApxjRKk6hlcN4= User-Agent: curl/7.29.0 Host: examplebucket.obs.region.myhuaweicloud.com Date: Wed, 01 Jul 2015 02:37:22 GMT Content-Type: application/xml ``` #### 响应示例：关闭桶日志转存 ``` HTTP/1.1 200 OK x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCSalxuWjLa91ewuXRoIcCKZFjFgCrYn0 x-obs-request-id: 0000018A2BC32FB6D2C62C9689DD14B3 Server: OBS Content-Length: 0 Date: Wed, 01 Jul 2015 02:37:22 GMT ``` #### 使用SDK调用接口 建议您使用OBS SDK调用接口。SDK对API进行了封装以简化您的开发工作，直接调用SDK接口函数即可访问OBS，无需手动计算签名。 | [Java](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_1502.html) | [Python](https://support.huaweicloud.com/sdk-python-devg-obs/obs_22_0816.html) | [C](https://support.huaweicloud.com/sdk-c-devg-obs/obs_20_1102.html) | [Go](https://support.huaweicloud.com/sdk-go-devg-obs/obs_33_0418.html) | [BrowserJS](https://support.huaweicloud.com/sdk-browserjs-devg-obs/obs_24_1102.html) | [.NET](https://support.huaweicloud.com/sdk-dotnet-devg-obs/obs_25_1102.html) | [Android](https://support.huaweicloud.com/sdk-android-devg-obs/obs_26_1102.html) | [iOS](https://support.huaweicloud.com/sdk-ios-devg-obs/obs_27_1102.html) | [PHP](https://support.huaweicloud.com/sdk-php-devg-obs/obs_28_1102.html) | [Node.js](https://support.huaweicloud.com/sdk-nodejs-devg-obs/obs_29_1102.html) | |---|---|---|---|---|---|---|---|---|---| #### 相关文档 - 使用obsutil设置桶日志，请参见[日志文件](https://support.huaweicloud.com/utiltg-obs/obs_11_0056.html)。 - 了解更多有关桶日志信息，请参见[配置桶的日志记录](https://support.huaweicloud.com/usermanual-obs/obs_03_0329.html)。 - API操作涉及的计费项参见[计费项](https://support.huaweicloud.com/price-obs/obs_42_0002.html)。