本頁面由 Cloud Translation API 翻譯而成。

使用記錄檔和儲存空間記錄檔

本文將說明如何下載及檢閱 Cloud Storage 值區的使用記錄和儲存空間資訊，並使用 Google BigQuery 分析記錄。

簡介

Cloud Storage 提供 CSV 檔案格式的使用記錄和儲存空間記錄，供您下載和查看。每小時建立的「使用記錄檔」可提供針對特定值區提出的所有要求的相關資訊。每天建立的「儲存記錄檔」則可提供最近一天內該值區消耗的儲存空間大小資訊。

設定完成後，系統會自動為指定值區產生用量記錄和儲存空間記錄，並儲存於您指定的值區中。

使用記錄檔和儲存空間記錄檔的定價，與儲存在 Cloud Storage 中的其他物件相同。

您應該使用用量記錄還是 Cloud 稽核記錄？

在大多數情況下，Cloud 稽核記錄是產生記錄檔以追蹤在 Cloud Storage 中執行的 API 作業的建議方法。

Cloud 稽核記錄會持續追蹤存取情況，並在事件發生後幾秒內傳送事件。
Cloud 稽核記錄產生的記錄更易於使用。
Cloud 稽核記錄可以監控許多 Google Cloud 服務，而不只是 Cloud Storage。
Cloud 稽核記錄可選擇記錄詳細的要求和回應資訊。

在某些情況下，您可能會想使用用量記錄，而非 Cloud 稽核記錄，或同時使用兩者。如果是以下情況，使用量記錄可能比較合適：

您想要追蹤因資源的存取權控制設定中含有 allUsers 或 allAuthenticatedUsers 而發生的存取情況，例如存取您已設為靜態網站的值區內的資產。
想要追蹤物件生命週期管理或自動調整級別功能進行的變更。
想要在記錄檔中包含延遲資訊、個別 HTTP 要求的要求及回應大小，或完整網址路徑和每個查詢參數。
您只想追蹤專案中特定值區的存取情況，因此不想啟用資料存取稽核記錄 (這會追蹤專案中所有值區的存取情況)。

請注意，用量記錄每小時只會產生一次，因此可能會延遲，尤其是回報要求率高的儲存空間時。

您應該使用儲存空間記錄檔還是 Monitoring？

一般而言，請不要使用儲存空間記錄檔。建議使用 Monitoring 做為測量儲存空間用量的工具，Monitoring 可提供各種視覺化工具，還有儲存記錄檔無法提供的其他儲存空間用量相關指標。如需使用 Monitoring 的逐步操作說明，請參閱主控台分頁，瞭解如何判斷值區大小。

設定記錄檔傳送

設定記錄檔傳送功能前，您必須先建立用於儲存記錄檔的 bucket。這個值區必須符合下列規定，否則記錄作業會失敗：

儲存記錄的 bucket 必須與記錄的 bucket 位於同一個機構。
- 如果記錄的 bucket 不屬於任何機構，則儲存記錄的 bucket 必須與記錄的 bucket 位於同一專案中。
如果您使用或啟用 VPC Service Controls，儲存記錄的值區必須與記錄的值區位於相同的安全範圍。

如果沒有符合這些條件的值區，請建立值區。

下列步驟說明如何為值區設定記錄傳送功能：

指令列

將值區的 roles/storage.objectCreator 角色授予 Cloud Storage：
```
gcloud storage buckets add-iam-policy-binding gs://example-logs-bucket --member=group:cloud-storage-analytics@google.com --role=roles/storage.objectCreator
```
這個角色會以群組 cloud-storage-analytics@google.com 的形式，授予 Cloud Storage 權限，以便建立及儲存記錄檔 (以新物件的形式)。

記錄物件具有記錄值區的預設物件 ACL，除非值區已啟用統一值區層級存取權。
使用 --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

授予 Cloud Storage 值區的 roles/storage.objectCreator 角色。如果值區有其他值區層級的 IAM 繫結，請務必在要求中納入這些繫結。
```
POST /storage/v1/b/example-logs-bucket/iam
Host: storage.googleapis.com
{
  "bindings":[
    {
      "role": "roles/storage.objectCreator",
      "members":[
        "group-cloud-storage-analytics@google.com"
      ]
    }
  ]
}
```
這個角色會以群組 cloud-storage-analytics@google.com 的形式，授予 Cloud Storage 權限，以便建立及儲存記錄檔 (以新物件的形式)。

記錄物件具有記錄值區的預設物件 ACL，除非值區已啟用統一值區層級存取權。

使用下列要求啟用值區的記錄功能：

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

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

XML API

進行權限設定，允許 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>
    <!-- include other existing ACL entries here-->
  </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>

查看記錄狀態

指令列

使用 buckets describe 指令並加上 --format 旗標，即可檢查記錄：

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

下載記錄檔

儲存空間記錄一天產生一次，內容包含前一天的儲存空間用量；通常會在太平洋標準時間上午 10:00 前建立。

只要受監控的值區中有需要報告的活動，系統將每小時產生一次使用記錄；通常是在每個小時結束後的 15 分鐘內建立。

如要從儲存記錄檔的 bucket 下載使用情形記錄檔和儲存空間記錄檔，最簡單的做法是透過 Google Cloud 控制台或 gcloud storage CLI。系統會採用以下命名慣例將用量記錄儲存為 CSV 格式：

OBJECT_PREFIX_usage_TIMESTAMP_ID_v0

同樣地，儲存空間記錄採用的命名慣例如下：

OBJECT_PREFIX_storage_TIMESTAMP_ID_v0

舉例來說，以下是使用預設物件前置字串的使用情形記錄物件名稱，會回報名為 example-bucket 的值區使用情形，且建立時間為世界標準時間 2022 年 6 月 18 日下午 2: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

如要下載記錄檔，請按照下列步驟操作：

控制台

在 Google Cloud 控制台，前往「Cloud Storage bucket」頁面。

前往「Buckets」(值區) 頁面
選取儲存記錄的 bucket。
按一下相應的記錄檔物件，即可下載或查看記錄檔。

指令列

執行下列指令：

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

選取預設專案。

如要進一步瞭解如何選取專案，請參閱「處理專案」。

建立新的資料集。

$ bq mk storageanalysis
Dataset 'storageanalysis' successfully created.

列出專案中的資料集：

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

將使用情形及儲存空間的結構定義儲存到本機電腦，以供載入指令使用。

您可在以下位置找到要使用的結構定義：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 檔案)。
- 略過每個記錄檔的第一列，因為該列包含資料欄說明。
以這裡的例子來說，這是您第一次執行載入指令，因此系統會建立 usage 和 storage 資料表。您可以使用不同的用量記錄檔名稱或萬用字元，繼續對這些資料表附加後續載入指令。舉例來說，下列指令會將開頭為「bucket_usuage_2014」的所有記錄檔中的資料附加到 storage 資料表。
```
$ bq load --skip_leading_rows=1 storageanalysis.usage \
      gs://example-logs-bucket/bucket_usage_2014* \
      ./cloud_storage_usage_schema_v0.json
```
使用萬用字元時，您可將已上傳到 BigQuery 的記錄檔移到另一個目錄 (例如gs://example-logs-bucket/processed)，以免從同一個記錄檔重複上傳資料。

您也可以透過 BigQuery 瀏覽器工具存取 BigQuery 功能。使用瀏覽器工具時，您可藉由建立資料表的程序來載入資料。

如要進一步瞭解如何從 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) 環境中使用。
```
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"
```

將儲存空間用量記錄檔載入 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 工具的互動殼層。
```
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`。這個值可以為空值。
`cs_bucket`	字串	要求中指定的值區。
`cs_object`	字串	使用者在要求中指定的物件。可能為空值。

儲存空間記錄檔欄位：

欄位	類型	說明
`bucket`	字串	值區名稱。
`storage_byte_hours`	整數	值區 24 小時期間的平均大小 (位元組-小時)。如要取得值區的總大小，請將位元組-小時除以 24。

使用記錄檔和儲存空間記錄檔 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

簡介

您應該使用用量記錄還是 Cloud 稽核記錄？

您應該使用儲存空間記錄檔還是 Monitoring？

設定記錄檔傳送

指令列

REST API

JSON API

XML API

查看記錄狀態

指令列

REST API

JSON API

XML API

下載記錄檔

控制台

指令列

在 BigQuery 中分析記錄

將記錄檔載入 BigQuery

修改用量記錄結構定義

在 BigQuery 中查詢記錄檔

停用記錄

指令列

REST API

JSON API

XML API

使用情形和儲存空間記錄檔格式

使用記錄檔和儲存空間記錄檔