访问日志和存储日志

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

简介

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

注意：访问日志不一定会及时和完整传送。

您应该使用访问日志还是 Cloud Audit Logs？

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

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

某些情况下，建议您改用访问日志。对于下述情形，最适合使用访问日志：

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

您应该使用存储日志还是 Stackdriver？

通常，您不应使用存储日志。Stackdriver 是推荐用来衡量存储空间使用情况的工具，它提供了可视化工具以及存储日志不提供的其他存储空间使用情况相关指标。如需了解使用 Stackdriver 的分步说明，请参阅确定存储分区的大小。

设置日志传送

注意：如果使用或启用 VPC Service Controls，记录的存储分区和存储日志数据的存储分区必须位于相同的安全边界内，否则日志记录将失败。

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

gsutil

1. 创建一个存储分区以用于存储您的日志。

   使用以下命令创建一个存储分区以用于存储您的日志：

   gsutil mb gs://example-logs-bucket

2. 设置权限以使 Cloud Storage 对该存储分区具有 WRITE 权限。

   Cloud Storage 必须具有 WRITE 权限才能以新对象形式创建并存储您的日志。要为 Cloud Storage 授予您的存储分区的 WRITE 访问权限，请使用以下命令向 [e-mail] 组授予写入权限：

   gsutil acl ch -g [e-mail]:W gs://example-logs-bucket

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

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

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

   您可以使用 logging 命令为您的存储分区启用日志记录功能：

   gsutil logging set on -b gs://example-logs-bucket [-o log_object_prefix ] gs://example-bucket

   您可以选择为日志对象设置 log_object_prefix 对象前缀。此对象前缀构成了日志对象名称的开头。日志对象名称最多可以包含 900 个字符，且必须为有效对象名称。默认情况下，对象前缀是启用了日志的存储分区的名称。

XML API

1. 创建一个存储分区以用于存储您的日志。

   使用以下请求创建一个存储分区以用于存储您的日志：

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

2. 设置权限以使 Cloud Storage 对该存储分区具有 WRITE 权限。

   Cloud Storage 必须具有 WRITE 权限才能以新对象形式创建并存储您的日志。要为 Cloud Storage 授予您的存储分区的 WRITE 访问权限，请为该存储分区添加一个 ACL 条目，以便向 [e-mail] 组授予写入权限。请确保在请求中包含此新 ACL 以及该存储分区的所有现有 ACL。

   PUT /example-logs-bucket?acl HTTP/1.1
   Host: storage.googleapis.com
   
   <AccessControlList>
     <Entries>
       <Entry>
         <Scope type="GroupByEmail">
           <EmailAddress>[e-mail]</EmailAddress>
         </Scope>
        <Permission>WRITE</Permission>
       </Entry>
       <!-- include other existing ACL entries here-->
     </Entries>
   </AccessControlList>
   

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

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

   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

1. 创建一个存储分区以用于存储您的日志。

   使用以下请求创建一个存储分区以用于存储您的日志：

   POST /storage/v1/b?project=project-id
   Host: storage.googleapis.com
   
   {
     "name": "example-logs-bucket"
   }
   

2. 设置权限以使 Cloud Storage 对该存储分区具有 WRITE 权限。

   Cloud Storage 必须具有 WRITE 权限才能以新对象形式创建并存储您的日志。要为 Cloud Storage 授予您的存储分区的 WRITE 访问权限，请为该存储分区添加一个 ACL 条目，以便向 [e-mail] 组授予写入权限。要实现此目的，您可以对日志存储分区的 BucketAccessControls 资源发出以下请求：

   POST /storage/v1/b/example-logs-bucket/acl
   Host: storage.googleapis.com
   {
    "entity": "[e-mail]",
    "role": "WRITER"
   }
   

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

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

   PATCH /storage/v1/b/example-bucket
   Host: storage.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: storage.googleapis.com

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

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

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

{
}

下载日志

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

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

注意：

• 在对使用情况日志执行任何日志处理操作时，应考虑这些日志的传送可能会延迟，也就是说，它们可能不会在一小时结束 15 分钟后立即传送。
• 通常，每小时使用情况日志对象包含在相应小时内发生的所有使用记录。有时，每小时使用情况日志对象会包含前一小时的记录，但绝不会包含后一小时的记录。
• Cloud Storage 可能会针对同一小时写入多个日志对象。
• 有时，单个记录可能会在使用情况日志中出现两次。我们会尽力移除重复记录，但如果移除重复记录对于您的日志分析至关重要，您所执行的日志处理操作也应该能够做到这一点。您可以使用 s_request_id 字段检测重复项。

对您的日志的访问权限由日志对象的 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

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

控制台

1. 在 Google Cloud Console 中打开 Cloud Storage 浏览器。
   打开 Cloud Storage 浏览器

2. 选择您的日志存储分区。

3. 通过点击相应日志对象，下载或查看您的日志。

gsutil

运行以下命令：

gsutil cp <logs_object> <destination_uri>

在 BigQuery 中分析日志

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

将日志加载到 BigQuery 中

1. 选择默认项目。

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

2. 创建新数据集。

   $ bq mk storageanalysis
   Dataset 'storageanalysis' successfully created.
   

3. 列出项目中的数据集：

   $ bq ls
    
   datasetId
   -----------------
   storageanalysis
   

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

   您可在以下位置找到要使用的架构： cloud_storage_usage_schema_v0 和 cloud_storage_storage_schema_v0。访问和存储日志格式部分中也对这些架构进行了介绍。

5. 将访问日志加载到数据集中。

   $ 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
   

   使用通配符时，建议您将已上传至 BigQuery 的日志移至其他目录（例如 gs://example-logs-bucket/processed），以避免多次上传同一日志中的数据。

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

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

修改访问日志架构

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

1. 如下所示，修改现有架构 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"}
   ]
   

2. 根据新架构对存储访问日志文件进行预处理，然后将这些文件加载到 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"
   

3. 当您将存储访问日志加载到 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 浏览器工具执行下面的查询。

1. 在 bq 工具中，进入交互模式。

   $ bq shell
   

2. 对存储日志表运行查询。

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

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

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

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

4. 退出 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。