文档首页/ 对象存储服务 OBS/ API参考/ 桶API/ 桶日志/ 设置桶日志管理配置-SetBucketLogging
更新时间：2026-07-13 GMT+08:00
查看PDF
分享

设置桶日志管理配置-SetBucketLogging

功能介绍

用户在创建或访问桶时，默认是不生成桶日志的。用户可通过打开日志配置管理开关，开启桶日志功能。OBS会为您记录跟桶操作相关的各种请求日志，产生的桶日志记录会被存储至同账号同区域下的同一个桶或其他桶中，便于您通过检索和分析日志来完成异常事件回溯和定位等工作。了解更多有关桶日志信息，请参见配置桶的日志记录。

接口约束

  • 日志可以存储在产生日志的源桶，也可以存储在其他桶，但日志存储桶和源桶必须属于同一账号下的相同区域。

    将源桶产生的日志文件存储至日志存储桶，该操作本身也会生成新的日志，此时如果源桶和日志存储桶是同一个，则存储日志操作生成的日志会再次被存储，导致日志不断循环产生。因此，建议您将源桶和日志存储桶配置为不同的桶。

  • 默认存储类别为低频访问存储或归档存储的桶不能作为存放日志文件的桶。日志文件存放到桶中后，这些日志文件会占用空间，并按照用户存放数据同样的计费策略进行计费。

授权信息

调用接口需要的授权

您必须是桶拥有者或拥有设置桶日志管理配置的权限，才能调用本接口，建议使用IAM或桶策略进行授权。了解更多OBS授权方式请参见OBS不同权限控制方式的区别。

  • 如果使用IAM授权，那么请在“角色与策略授权”、“身份策略授权”两种IAM授权方式中选择一种，并配置相应权限：
    • 如果使用角色与策略授权（旧版IAM，即IAM v3接口），需具备obs:bucket:PutBucketLogging权限，授权操作请参见创建IAM自定义策略。
    • 如果使用身份策略授权（新版IAM，即IAM v5接口），如下表所示，需具备obs:bucket:putBucketLogging权限，授权操作请参见创建IAM自定义身份策略。

      授权项

      Action

      访问级别

      Access Level

      资源类型（*为必须）

      Resource Type (*: required)

      条件键

      Condition Key

      别名

      Alias

      依赖的授权项

      Dependencies

      obs:bucket:putBucketLogging

      Write

      bucket *

      -

      -

      -
      • obs:EpochTime
      • obs:SourceIp
      • obs:TlsVersion
      • obs:CustomDomain
  • 如果使用桶策略进行授权，需具备obs:bucket:PutBucketLogging权限，具体操作请参见自定义创建桶策略。

URI

PUT /

调用方法

请参见如何调用API。调用前需要先计算API签名，并将签名添加到请求中。

您还可以使用API Explorer在线调试接口。

请求消息样式

以下为请求消息样例，请将示例中的BucketName修改为您的桶名，RegionID修改为桶所在的区域ID，可参考支持区域获取区域ID。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
 
PUT /?logging HTTP/1.1 
Host: BucketName.obs.RegionID.myhuaweicloud.com 
Date: GMT 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>

URI参数（URI Parameters）

表1 URI参数

参数名称

参数类型

是否必选

描述

logging

String

否

参数解释：

用于标识API接口与桶日志有关。

约束限制：

无。

取值范围：

logging

默认取值：

不涉及

请求头参数（Request headers）

该请求使用公共请求头，具体参见表3。

请求体参数（Request body）

表2 请求体参数

元素名字

元素类型

是否必选

描述

BucketLoggingStatus

Container

是

参数解释：

日志状态信息的容器。当BucketLoggingStatus为空时，桶日志功能关闭。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

Agency

String

当设置logging时，必选；

当关闭logging时，勿选。

参数解释：

目标桶Owner通过统一身份认证服务创建的对OBS服务的委托的名称。创建委托详见创建委托。

约束限制：

委托必须为“对象存储服务 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个字节。

默认取值：

不涉及。

TargetGrants

Container

否

参数解释：

授权信息的容器。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

存储访问日志的object命名规则

1
 
<TargetPrefix>YYYY-mm-DD-HH-MM-SS-<UniqueString>
  • <TargetPrefix>为用户指定的目标前缀。TargetPrefix对应请求体中的TargetPrefix元素。
    • 如果<TargetPrefix>以“/”结尾，则在控制台上看到桶生成的日志文件，将统一被存放在目标桶中的以<TargetPrefix>命名的文件夹中，日志文件名称为“YYYY-mm-DD-HH-MM-SS-<UniqueString>”。而实际上OBS没有文件夹的概念，为了方便用户管理数据，OBS通过在对象的名称中增加“/”的方式来模拟文件夹，因此通过API看到桶生成的日志文件名称仍然为“<TargetPrefix>YYYY-mm-DD-HH-MM-SS-<UniqueString>”。

      一个实际用于存储OBS访问日志的object名称示例如下：

      1
      		 
      bucket-log/2015-06-29-12-22-07-N7MXLAF1BDG7MPDV
      • "bucket-log/"为用户指定的目标前缀。
      • "2015-06-29-12-22-07"为日志生成的日期与时间。
      • "N7MXLAF1BDG7MPDV"为OBS自动生成的字符串。
    • 如果<TargetPrefix>不以“/”结尾，则在控制台上看到桶生成的日志文件，将直接被存储在目标桶的根目录下，日志文件名称为“<TargetPrefix>YYYY-mm-DD-HH-MM-SS-<UniqueString>”。此时通过API看到桶生成的日志文件名称仍然为“<TargetPrefix>YYYY-mm-DD-HH-MM-SS-<UniqueString>”。

      一个实际用于存储OBS访问日志的object名称示例如下：

      1
      		 
      bucket-log2015-06-29-12-22-07-N7MXLAF1BDG7MPDV
      • "bucket-log"为用户指定的目标前缀。
      • "2015-06-29-12-22-07"为日志生成的日期与时间。
      • "N7MXLAF1BDG7MPDV"为OBS自动生成的字符串。
  • YYYY-mm-DD-HH-MM-SS为日志生成的日期与时间，各字段依次表示年、月、日、时、分、秒。
  • <UniqueString>为OBS自动生成的字符串。

桶访问日志格式

以下所示为在目标桶生成的桶访问日志文件记录：字段间使用空格分隔，包含空格的字段用双引号包裹。

1
 
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" - -

每个桶访问日志都包含如下信息：

表3 Bucket Logging格式

参数名称

参数类型

含义

BucketOwner

String

参数解释：

桶的ownerId。

示例：787f2f92b20943998a4fe2ab75eb09b8

取值范围：

租户id：获取方式请参考获取账号、IAM用户、项目、用户组、区域、委托的名称和ID。

Bucket

String

参数解释：

桶名。

示例：bucket。

取值范围：

桶名命名规则请参考桶命名规则。

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。

匿名用户：Anonymous。

RequestID

String

参数解释：

请求ID。

示例：

281599BACAD9376ECE141B842B94535B

取值范围：

通常为32位数字+字母组成的字符串。

Operation

String

参数解释：

操作名称。

示例：

REST.GET.BUCKET.LOCATION

取值范围：

OBS所有接口。

Key

String

参数解释：

对象名。

示例：

-

取值范围：

对象名取值参考对象键命名指导原则。

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。

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

取值范围：

AccessKeyID

String

参数解释：

请求者的AccessKey ID。取值-表示匿名请求。

示例：

UDSIAMSTUBTEST002852

取值范围：

请求者的AccessKey ID。匿名请求该字段为“-”。

响应消息样式

1
2
3
 
HTTP/1.1 status_code
Date: date
Content-Length: length

响应头 (Response Headers)

该请求的响应消息使用公共响应头，具体请参考表1。

响应体 (Response Body)

本接口的响应消息中不携带响应体。

错误响应消息

无特殊错误，所有错误已包含在错误码概述中。

请求示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 
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

<?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>

响应示例

1
2
3
4
5
6
 
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
 
<BucketLoggingStatus>
</BucketLoggingStatus>

响应示例：关闭桶日志转存

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

Python

C

Go

BrowserJS

.NET

Android

iOS

PHP

Node.js

相关文档

父主题： 桶日志

相关文档