访问日志和存储日志

本文档介绍如何下载和查看与 Cloud Storage 存储分区相关的访问日志及存储信息，以及如何使用 Google BigQuery 分析这些日志。

简介

Cloud Storage 提供 CSV 文件形式的访问日志和存储日志，以方便您下载和查看。访问日志是每小时创建一次，其中提供针对指定存储分区发出的所有请求的信息，而每日存储日志提供的是有关该存储分区过去一天内存储空间使用情况的信息。系统会自动在您指定的存储分区中以新对象形式创建访问日志和存储日志。

如果您将 Cloud Storage 存储分区配置为模拟静态网站的行为，建议您记录网站中资源的使用方式。请注意，您还可以为任何 Cloud Storage 存储分区配置存储分区访问日志和存储日志。

您是应使用访问和存储日志还是 Cloud Audit Logging？

大多数情况下，推荐使用 Cloud Audit Logs 生成日志，用于跟踪 Cloud Storage 中执行的 API 操作：

Cloud Audit Logs 可以持续跟踪访问。
Cloud Audit Logs 生成的日志更易于使用。
Cloud Audit Logs 可监控许多 Google Cloud Platform 服务，而不仅仅是监控 Cloud Storage。

某些情况下，建议您改用访问和存储日志。

对于下述情形，最适合使用访问日志：

您想要跟踪对公开对象的访问。
您想要通过为对象设置访问控制列表 (ACL) 独占授予访问权限并希望跟踪对这些对象的访问。
您想要跟踪通过对象生命周期管理功能进行的更改。
您打算使用经过身份验证的浏览器下载访问存储分区中的对象。
您希望日志包含延迟信息，或各个 HTTP 请求的请求和响应大小。

在下述情形中，最适合使用存储日志：

您希望跟踪存储分区中存储的数据量。请注意，此信息以及存储分区的对象计数在 Stackdriver 中也可用。

设置日志传送

以下步骤描述了如何使用 gsutil 工具、XML API 和 JSON API 为特定存储分区设置日志传送。如果您没有 gsutil 工具，可以将该工具作为 Google Cloud SDK 软件包的一部分一起下载并安装，也可以将其作为一个独立产品进行下载并安装。

gsutil

创建一个存储分区以用于存储您的日志。
使用以下命令创建一个存储分区以用于存储您的日志：
```
gsutil mb gs://example-logs-bucket
```
设置权限以使 Cloud Storage 对该存储分区具有 WRITE 权限。
Cloud Storage 必须具有 WRITE 权限才能以新对象形式创建并存储您的日志。要为 Cloud Storage 授予您的存储分区的 WRITE 访问权限，请使用以下命令向 cloud-storage-analytics@google.com 组授予写入访问权限：
```
gsutil acl ch -g cloud-storage-analytics@google.com:W gs://example-logs-bucket
```

日志对象将具有日志存储分区的默认对象 acl。您可以使用 gsutil 为日志存储分区设置默认对象 acl。例如，要将默认对象 acl 设置为项目专用，请使用以下命令：

gsutil defacl set project-private gs://example-logs-bucket

为您的存储分区启用日志记录功能。
您可以使用 logging 命令为您的存储分区启用日志记录功能：
```
gsutil logging set on -b gs://example-logs-bucket [-o log_object_prefix ] gs://example-bucket
```
您还可以选择为您的日志对象设置 log_object_prefix 对象前缀。此对象前缀构成了日志对象名称的开头。日志对象名称最多可以包含 900 个字符，且必须为有效对象名称。默认情况下，对象前缀是启用了日志的存储分区的名称。

XML API

创建一个存储分区以用于存储您的日志。
使用以下请求创建一个存储分区以用于存储您的日志：
```
PUT /example-logs-bucket HTTP/1.1
Host: storage.googleapis.com
```
设置权限以使 Cloud Storage 对该存储分区具有 WRITE 权限。
Cloud Storage 必须具有 WRITE 权限才能以新对象形式创建并存储您的日志。要为 Cloud Storage 授予您的存储分区的 WRITE 访问权限，请为该存储分区添加一个 ACL 条目，以便向 cloud-storage-analytics@google.com 组授予写入访问权限。请确保在请求中包含此新 ACL 以及该存储分区的所有现有 ACL。
```
PUT /example-logs-bucket?acl HTTP/1.1
Host: storage.googleapis.com

<AccessControlList>
  <Entries>
    <Entry>
      <Scope type="GroupByEmail">
        <EmailAddress>cloud-storage-analytics@google.com</EmailAddress>
      </Scope>
     <Permission>WRITE</Permission>
    </Entry>
    
  </Entries>
</AccessControlList>
```

为您的存储分区启用日志记录功能。

您可以使用日志记录查询参数为您的存储分区启用日志记录功能：

PUT /example-bucket?logging HTTP/1.1
Host: storage.googleapis.com

<Logging>
    <LogBucket>example-logs-bucket</LogBucket>
    <LogObjectPrefix>log_object_prefix</LogObjectPrefix>
</Logging>

JSON API

创建一个存储分区以用于存储您的日志。
使用以下请求创建一个存储分区以用于存储您的日志：
```
POST /storage/v1/b?project=project-id
Host: www.googleapis.com

{
  "name": "example-logs-bucket"
}
```
设置权限以使 Cloud Storage 对该存储分区具有 WRITE 权限。
Cloud Storage 必须具有 WRITE 权限才能以新对象形式创建并存储您的日志。要为 Cloud Storage 授予您的存储分区的 WRITE 访问权限，请为该存储分区添加一个 ACL 条目，以便向 cloud-storage-analytics@google.com 组授予写入访问权限。要实现此目的，您可以对日志存储分区的 BucketAccessControls 资源发出以下请求：
```
POST /storage/v1/b/example-logs-bucket/acl
Host: www.googleapis.com
{
 "entity": "group-cloud-storage-analytics@google.com",
 "role": "WRITER"
}
```

为您的存储分区启用日志记录功能。

您可以使用以下请求为您的存储分区启用日志记录功能：

PATCH /storage/v1/b/example-bucket
Host: www.googleapis.com

{
 "logging": {
  "logBucket": "example-logs-bucket",
  "logObjectPrefix": "log_object_prefix"
 }
}

检查日志记录状态

gsutil

使用 gsutil 时，您可以通过 logging get 命令检查日志记录：

gsutil logging get gs://example-bucket

您还可以将日志记录配置保存到文件中：

gsutil logging get gs://example-bucket > your_logging_configuration_file

如果启用了日志记录功能，则服务器将在响应中返回日志记录配置：

{"logBucket": "example-logs-bucket", "logObjectPrefix": "log_object_prefix"}

如果未启用日志记录功能，服务器则会返回以下内容：

gs://example-bucket/ has no logging configuration.

XML API

使用 Cloud Storage XML API，您可以发送 GET Bucket 请求来获取存储分区的日志记录配置，如以下示例所示。

GET /example-bucket?logging HTTP/1.1
Host: storage.googleapis.com

如果启用了日志记录功能，则服务器将在响应中发送相关配置。响应可能类似如下所示：

<?xml version="1.0" ?>
<Logging>
    <LogBucket>
        example-logs-bucket
    </LogBucket>
    <LogObjectPrefix>
        log_object_prefix
    </LogObjectPrefix>
</Logging>

如果未启用日志记录功能，服务器则会返回空配置：

<?xml version="1.0" ?>
<Logging/>

JSON API

使用 Cloud Storage JSON API，您可以发送 GET 请求来获取存储分区的日志记录配置，如以下示例所示。

GET /storage/v1/b/example-bucket?fields=logging
Host: www.googleapis.com

如果启用了日志记录功能，则服务器将在响应中发送相关配置。响应可能类似如下所示：

{
 "logging": {
  "logBucket": "example-logs-bucket",
  "logObjectPrefix": "log_object_prefix"
  }
}

如果未启用日志记录功能，服务器则会返回空配置：

{
}

下载日志

存储日志每天生成一次，其中包含前一天的存储空间使用情况。系统通常在太平洋标准时间 (PST) 上午 10:00 之前创建这些日志。

如果受监控存储分区中存在要报告的活动，系统会每小时生成一次使用情况日志。系统通常会在一小时结束 15 分钟后创建这些日志。

对您的日志的访问权限由日志对象的 ACL 控制。日志对象具有日志存储分区的默认对象 acl。

要下载您的访问日志和存储日志，最简单的方式是通过 Google Cloud Platform Console 或使用 gsutil 工具。访问日志为 CSV 格式并采用以下命名惯例：

gs://<bucket_name>/<object_prefix>_usage_<timestamp>_<id>_v0

例如，以下所示为名为 gs://example-bucket 的存储分区的访问日志对象，该对象创建于 2013 年 6 月 18 日 14:00 (UTC) 并存储在 gs://example-logs-bucket 存储分区中：

gs://example-logs-bucket/example-bucket_usage_2013_06_18_14_00_00_1702e6_v0

存储日志采用以下命名惯例：

gs://<bucket_name>/<object_prefix>_storage_<timestamp>_<id>_v0

例如，以下所示为同一存储分区的存储日志对象，该对象创建于 2013 年 6 月 18 日：

gs://example-logs-bucket/example-bucket_storage_2013_06_18_07_00_00_1702e6_v0

要下载日志，请按如下所述操作：

Console

在 Google Cloud Platform Console 中打开 Cloud Storage 浏览器。
打开 Cloud Storage 浏览器
选择您的日志存储分区。
通过点击相应日志对象，下载或查看您的日志。

gsutil

运行以下命令：

gsutil cp <logs_object> <destination_uri>

在 BigQuery 中分析日志

要查询您的 Cloud Storage 使用情况和存储日志，您可以使用 Google BigQuery，它可以针对仅支持附加的表格启用快速、类似 SQL 的查询。BigQuery 命令行工具 bq 是一款基于 Python 的工具，可让您通过命令行访问 BigQuery。如需了解如何下载和使用 bq，请参阅 bq 命令行工具参考页面。

将日志加载到 BigQuery 中

选择默认项目。

如需详细了解如何选择项目，请参阅使用项目。

创建新数据集。

$ bq mk storageanalysis
Dataset 'storageanalysis' successfully created.

列出项目中的数据集：

$ bq ls

datasetId
-----------------
storageanalysis

将使用情况和存储架构保存到您的本地计算机，以在 load 命令中使用。

您可在以下位置找到要使用的架构： cloud_storage_usage_schema_v0 和 cloud_storage_storage_schema_v0。访问和存储日志格式部分中也对这些架构进行了介绍。
将访问日志加载到数据集中。
```
$ bq load --skip_leading_rows=1 storageanalysis.usage \
      gs://example-logs-bucket/example-bucket_usage_2014_01_15_14_00_00_1702e6_v0 \
      ./cloud_storage_usage_schema_v0.json
$ bq load --skip_leading_rows=1 storageanalysis.storage \
      gs://example-logs-bucket/example-bucket_storage_2014_01_05_14_00_00_091c5f_v0 \
      ./cloud_storage_storage_schema_v0.json
```
这些命令执行以下操作：
- 从存储分区 example-logs-bucket 中加载使用情况和存储日志。
- 在 storageanalysis 数据集中创建 usage 和 storage 表。
- 从运行 bq 命令的同一目录中读取架构数据（.json 文件）。
- 跳过每个日志文件的第一行（因为其中包含列说明）。
由于这是您第一次在此处的示例中运行 load 命令，因此创建了 usage 和 storage 表。您可以在后续执行 load 命令时使用不同的访问日志文件名或通配符，以继续对这些表执行附加操作。例如，以下命令会将以“bucket_usuage_2014”开头的所有日志中的数据附加到 storage 表中：
```
$ bq load --skip_leading_rows=1 storageanalysis.usage \
      gs://example-logs-bucket/bucket_usage_2014* \
      ./cloud_storage_usage_schema.json
```
使用通配符时，建议您将已上传至 BiqQuery 的日志移至其他目录（例如 gs://example-logs-bucket/processed），以避免同一日志中的数据被上传多次。

您还可以通过 BigQuery 浏览器工具访问 BiqQuery 功能。使用此浏览器工具，您可以通过 create table 进程加载数据。

如需详细了解如何从 Cloud Storage 加载数据（包括以编程方式加载数据），请参阅从 Cloud Storage 加载数据。

修改访问日志架构

在某些情况下您可能会发现，在将访问日志加载到 BigQuery 之前先对其进行预处理会带来很多好处。例如，您可以向访问日志添加其他信息，以便在 BigQuery 中更轻松地进行查询分析。在本部分中，我们将展示如何将每个存储访问日志的文件名添加到该日志中。这需要修改现有架构和各日志文件。

如下所示，修改现有架构 cloud_storage_storage_schema_v0，以添加文件名。为新架构指定一个新名称（例如 cloud_storage_storage_schema_custom.json），以便与原始架构区分开来。
```
[  {"name": "bucket", "type": "string", "mode": "REQUIRED"},
{"name": "storage_byte_hours","type": "integer","mode": "REQUIRED"},
{"name": "filename","type": "string","mode": "REQUIRED"}
]
```
根据新架构对存储访问日志文件进行预处理，然后将这些文件加载到 BigQuery 中。

例如，可以在 Linux、macOS 或 Windows (Cygwin) 环境中使用以下命令：
```
gsutil cp gs://example-logs-bucket/example-bucket_storage\* .
for f in example-bucket_storage\*; do sed -i -e "1s/$/,\"filename\"/" -e "2s/$/,\""$f"\"/" $f; done
```
gsutil 命令会将文件复制到您的工作目录中。第二个命令会循环遍历各个日志文件，并将“filename”添加到说明行（第一行），将实际文件名添加到数据行（第二行）。以下是经过修改的日志文件示例：
```
"bucket","storage_byte_hours","filename"
"example-bucket","5532482018","example-bucket_storage_2014_01_05_08_00_00_021fd_v0"
```

当您将存储访问日志加载到 BigQuery 时，系统会加载您在本地修改的日志并使用自定义架构。

for f in example-bucket_storage\*; \
do ./bq.py load --skip_leading_rows=1 storageanalysis.storage $f ./cloud_storage_storage_schema_custom.json; done

在 BigQuery 中查询日志

将日志加载到 BigQuery 后，您可以对访问日志进行查询，以返回与所记录存储分区相关的信息。如果您有某一存储分区的数天访问日志，并且您已按照将访问日志加载到 BigQuery 所述加载这些日志，那么在此场景下，您可以按以下示例所示使用 bq 工具。也可以使用 BigQuery 浏览器工具执行下面的查询。

在 bq 工具中，进入交互模式。
```
$ bq shell
```

对存储日志表运行查询。

例如，以下查询将显示所记录存储分区的存储空间在一段时间内的变化情况。该查询假定您已按照修改访问日志架构中的说明修改存储访问日志，并已将日志文件命名为“logstorage*”。

project-name>SELECT SUBSTRING(filename, 13, 10) as day, storage_byte_hours/24 as size FROM [storageanalysis.storage] ORDER BY filename LIMIT 100

此查询的示例输出如下：

Waiting on bqjob_r36fbf5c164a966e8_0000014379bc199c_1 ... (0s) Current status: DONE
+------------+----------------------+
|    day     |         size         |
+------------+----------------------+
| 2014_01_05 | 2.3052008408333334E8 |
| 2014_01_06 | 2.3012297245833334E8 |
| 2014_01_07 | 3.3477797120833334E8 |
| 2014_01_08 | 4.4183686058333334E8 |
+-----------------------------------+

如果您没有修改架构而使用默认架构，可以运行以下查询：

project-name>SELECT storage_byte_hours FROM [storageanalysis.storage] LIMIT 100

对使用情况日志表运行查询。

例如，以下查询将显示如何汇总客户端在访问所记录存储分区中的资源时采用的请求方法。

project-name>SELECT cs_method, COUNT(\*) AS count FROM [storageanalysis.usage] GROUP BY cs_method

此查询的示例输出如下：

Waiting on bqjob_r1a6b4596bd9c29fb_000001437d6f8a52_1 ... (0s) Current status: DONE
+-----------+-------+
| cs_method | count |
+-----------+-------+
| PUT       |  8002 |
| GET       | 12631 |
| POST      |  2737 |
| HEAD      |  2173 |
| DELETE    |  7290 |
+-----------+-------+

退出 bq 工具的交互式 shell。
```
project-name> quit
```

停用日志记录功能

gsutil

使用 gsutil 时，您可以通过 logging 命令停用日志记录功能：

gsutil logging set off gs://example-bucket

要检查日志记录功能是否已成功停用，请执行 logging get 请求：

gsutil logging get gs://example-bucket

如果日志记录功能已停用，则返回以下内容：

gs://example-bucket/ has no logging configuration.

XML API

使用 Cloud Storage XML API 停用日志记录功能的方法是，发送 PUT 请求以获取存储分区的日志记录配置，如以下示例所示：

PUT /example-bucket?logging HTTP/1.1
Host: storage.googleapis.com

<Logging/>

JSON API

使用 Cloud Storage JSON API 停用日志记录功能的方法是，发送 PATCH 请求以获取存储分区的日志记录配置，如以下示例所示。

PATCH /example-bucket?logging HTTP/1.1
Host: storage.googleapis.com

{
 "logging": null
}

访问和存储日志格式

访问日志和存储日志可以提供大量信息。您可以借助以下表来识别这些日志中提供的所有信息。

访问日志字段：

字段	类型	说明
`time_micros`	整数	请求完成时间（与 Unix 计时原点之间相隔的微秒数）。
`c_ip`	字符串	从中发出请求的 IP 地址。“c”前缀表示这是有关客户端的信息。
`c_ip_type`	整数	c_ip 字段中的 IP 类型：值 1 表示 IPV4 地址。值 2 表示 IPV6 地址。
`c_ip_region`	字符串	留待将来使用。
`cs_method`	字符串	此请求的 HTTP 方法。“cs”前缀表示这是从客户端发送到服务器的信息。
`cs_uri`	字符串	请求的 URI。
`sc_status`	整数	服务器响应中发送的 HTTP 状态代码。“sc”前缀表示这是从服务器发送到客户端的信息。
`cs_bytes`	整数	请求中发送的字节数。
`sc_bytes`	整数	响应中发送的字节数。
`time_taken_micros`	整数	传送请求所花的时间（以微秒为单位），即从收到第一个字节算起，一直到发送响应为止请注意，对于续传，结束点取决于作为续传一部分的最终上传请求的响应。
`cs_host`	字符串	原始请求中的主机。
`cs_referer`	字符串	请求的 HTTP 引荐来源网址。
`cs_user_agent`	字符串	请求的用户代理。对于通过生命周期管理发出的请求，值为 `GCS Lifecycle Management`。
`s_request_id`	字符串	请求标识符。
`cs_operation`	字符串	Cloud Storage 操作，例如 `GET_Object`。
`cs_bucket`	字符串	请求中指定的存储分区。对于 list buckets 请求，该字段可为 null。
`cs_object`	字符串	此请求中指定的对象。该字段可为 null。

存储日志字段：

字段	类型	说明
`bucket`	字符串	存储分区的名称。
`storage_byte_hours`	整数	存储分区在 24 小时时段内的平均大小（以字节小时为单位）。要获取存储分区的总大小，请将字节小时除以 24。

简介

您是应使用访问和存储日志还是 Cloud Audit Logging？

设置日志传送

gsutil

XML API

JSON API

检查日志记录状态

gsutil

XML API

JSON API

下载日志

Console

gsutil

在 BigQuery 中分析日志

将日志加载到 BigQuery 中

修改访问日志架构

在 BigQuery 中查询日志

停用日志记录功能

gsutil

XML API

JSON API

访问和存储日志格式

发送以下问题的反馈：