使用情况日志和存储情况日志

本文档介绍如何下载和查看 Cloud Storage 存储桶的使用情况日志及存储信息，以及如何使用 Google BigQuery 分析这些日志。

简介

Cloud Storage 提供 CSV 文件形式的使用情况日志和存储日志，以方便您下载和查看。使用情况日志每小时创建一次，其中提供向指定存储桶发出的所有请求的信息。存储日志每天创建一次，其中提供过去一天该存储桶的存储空间使用情况的信息。

设置后，系统会自动在您指定的存储桶中以新对象形式创建使用情况日志和存储日志。

使用情况日志和存储日志与存储在 Cloud Storage 中的其他对象需具有相同的价格。

注意：使用情况日志不一定会及时和完整传送。

您应该使用有关使用情况的日志还是 Cloud Audit Logs？

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

• Cloud Audit Logs 会持续跟踪访问，并在事件发生后的几秒钟内传送事件。
• Cloud Audit Logs 生成的日志更易于使用。
• Cloud Audit Logs 可监控许多 Google Cloud 服务，而不仅仅是监控 Cloud Storage。
• Cloud Audit Logs 可以选择记录详细的请求和响应信息。

在某些情况下，您可能希望使用使用情况日志，而不是使用 Cloud Audit Logs 或搭配使用 Cloud Audit Logs。对于下述情形，最适合使用“使用情况日志”：

• 您想要跟踪访问（因为资源的访问权限控制设置中包含 allUsers 或 allAuthenticatedUsers），例如针对您已配置为静态网站的存储桶中的资源的访问。
• 您想要跟踪通过对象生命周期管理或 Autoclass 功能进行的更改。
• 您打算使用经过身份验证的浏览器下载访问存储桶中的对象。
• 您希望日志包含延迟时间信息、各个 HTTP 请求的请求和响应大小，或者完整的网址路径和每个查询参数。
• 您只想跟踪对项目中特定存储桶的访问，因此不希望启用数据访问审核日志，因为该日志会跟踪对项目中所有存储桶的访问。

请注意，使用情况日志每小时生成一次，可能会延迟，尤其是在报告出现高请求率的存储桶时。

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

通常，您不应使用存储日志。Monitoring 是推荐用来衡量存储空间使用情况的工具，它提供了可视化工具以及存储日志不提供的额外存储空间使用情况相关指标。如需了解使用 Monitoring 的分步说明，请参阅用于确定存储桶大小的“控制台”标签页。

设置日志传送

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

设置日志传送后，系统会为指定的存储桶生成使用情况日志和存储日志。以下步骤介绍了如何为存储桶设置日志传送。如果您还没有计划用于存储日志的存储桶，请创建存储桶。

命令行

1. 向 Cloud Storage 授予存储桶的 roles/storage.objectCreator 角色：

   gcloud storage buckets add-iam-policy-binding gs://example-logs-bucket --member=group:[e-mail] --role=roles/storage.objectCreator

   该角色将以群组 [e-mail] 的形式授予 Cloud Storage 创建日志并将其存储为新对象的权限。

   日志对象具有日志存储桶的默认对象 acl，除非已针对存储桶启用统一存储桶级访问权限。

2. 使用 --log-bucket 标志为您的存储桶启用日志记录功能：

   gcloud storage buckets update gs://example-bucket --log-bucket=gs://example-logs-bucket [--log-object-prefix=log_object_prefix]

   （可选）您可以使用 --log-object-prefix 标志为日志对象设置对象前缀。此对象前缀构成了日志对象名称的开头。日志对象名称最多可以包含 900 个字符，且必须为有效对象名称。 默认情况下，对象前缀是启用了日志的存储桶的名称。

REST API

JSON API

1. 向 Cloud Storage 授予存储桶的 roles/storage.objectCreator 角色。如果存储桶还有额外的存储桶级 IAM 绑定，请务必在请求中包含这些绑定。

   POST /storage/v1/b/example-logs-bucket/iam
   Host: storage.googleapis.com
   {
     "bindings":[
       {
         "role": "roles/storage.objectCreator",
         "members":[
           "[e-mail]"
         ]
       }
     ]
   }
   

   该角色将以群组 [e-mail] 的形式授予 Cloud Storage 创建日志并将其存储为新对象的权限。

   日志对象具有日志存储桶的默认对象 acl，除非已针对存储桶启用统一存储桶级访问权限。

2. 使用以下请求为您的存储桶启用日志记录功能：

   PATCH /storage/v1/b/example-bucket
   Host: storage.googleapis.com
   
   {
    "logging": {
     "logBucket": "example-logs-bucket",
     "logObjectPrefix": "log_object_prefix"
    }
   }
   

XML API

注意：如果您对存储日志的存储桶使用统一存储桶级访问权限，则不能使用 XML API 为其设置访问权限。请改用其他工具。

1. 设置权限以使 Cloud Storage 对该存储桶具有 WRITE 权限，以便创建日志并将其存储为新对象。您必须为授予群组 [e-mail] 写入权限的存储桶添加 ACL 条目。请确保在请求中包含此新 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>
   

2. 使用日志记录查询参数为您的存储桶启用日志记录功能：

   PUT /example-bucket?logging HTTP/1.1
   Host: storage.googleapis.com
   
   <Logging>
       <LogBucket>example-logs-bucket</LogBucket>
       <LogObjectPrefix>log_object_prefix</LogObjectPrefix>
   </Logging>
   

检查日志记录状态

命令行

使用带有 --format 标志的 buckets describe 命令检查日志记录：

gcloud storage buckets describe gs://example-bucket --format="default(logging_config)"

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

gcloud storage buckets describe gs://example-bucket > your_logging_configuration_file --format="default(logging_config)"

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

logging:
  logBucket: example-logs-bucket
  logObjectPrefix: log_object_prefix

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

null

REST API

JSON API

发送 GET 请求以获取存储桶的日志记录配置，如以下示例所示：

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

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

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

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

{}

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

下载日志

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

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

注意：

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

从存储桶中下载使用日志和存储日志的最简单方法是通过 Google Cloud 控制台或 gcloud storage CLI。使用情况日志为 CSV 格式并采用以下命名惯例：

OBJECT_PREFIX_usage_TIMESTAMP_ID_v0

类似地，存储日志采用以下命名惯例：

OBJECT_PREFIX_storage_TIMESTAMP_ID_v0

例如，以下是使用情况日志对象的名称，该名称使用默认对象前缀，报告名为 example-bucket 的存储桶的使用情况，且创建于世界协调时间 (UTC) 2022 年 6 月 18 日 14:00：

example-bucket_usage_2022_06_18_14_00_00_1702e6_v0

同样，以下是使用默认日志前缀且于 2022 年 6 月 18 日针对同一存储桶创建的存储日志对象的名称：

example-bucket_storage_2022_06_18_07_00_00_1702e6_v0

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

控制台

1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。
   

   进入“存储桶”

2. 选择存储日志的存储桶。

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

命令行

运行以下命令：

gcloud storage cp gs://BUCKET_NAME/LOGS_OBJECT DESTINATION

其中：

• BUCKET_NAME 是存储日志的存储桶的名称。例如 example-logs-bucket。

• LOGS_OBJECT 是要下载的使用情况日志或存储日志的名称。例如 example-bucket_usage_2022_06_18_14_00_00_1702e6_v0。

• DESTINATION 是日志下载到的位置。例如 Desktop/Logs。

在 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) 环境中使用以下命令：

   gcloud storage 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
   

   gcloud storage 命令会将文件复制到您的工作目录中。第二个命令会循环遍历各个日志文件，并将“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
   

停用日志记录

命令行

在 buckets update 命令中使用 --clear-log-bucket 标志停用日志记录功能：

gcloud storage buckets update gs://example-bucket --clear-log-bucket

如需检查日志记录功能是否已成功停用，请使用 buckets describe 命令：

gcloud storage buckets describe gs://example-bucket --format="default(logging_config)"

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

null

REST API

JSON API

停用日志记录功能的方法是，发送 PATCH 请求以获取存储桶的日志记录配置，如以下示例所示。

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

{
 "logging": null
}

XML API

停用日志记录功能的方法是，发送 PUT 请求以获取存储桶的日志记录配置，如以下示例所示：

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

<Logging/>

使用情况和存储日志格式

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

使用情况日志字段：

字段	类型	说明
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。 此字段可为 null。
cs_bucket	字符串	请求中指定的存储桶。
cs_object	字符串	此请求中指定的对象。该字段可为 null。

存储日志字段：

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