使用状況ログとストレージログ

このドキュメントでは、Cloud Storage バケットの使用状況ログとストレージログをダウンロードして確認する方法と、Google BigQuery を使用してログを分析する方法について説明します。

はじめに

Cloud Storage では、使用状況ログとストレージログを CSV ファイル形式で提供しており、ダウンロードと表示が可能です。使用状況ログには、特定のバケットに対して行われたすべてのリクエストの情報が含まれ、1 時間ごとに作成されます。ストレージログには、前日のバケットのストレージ消費についての情報が含まれ、毎日作成されます。

設定されると、使用状況ログとストレージログは、指定したバケット内に新しいオブジェクトとして自動的に作成されます。

使用状況ログとストレージログには、Cloud Storage に保存されている他のオブジェクトと同じ料金が適用されます。

使用状況ログと Cloud Audit Logs の使い分け

ほとんどのケースで、Cloud Storage で実行された API オペレーションを追跡するログの生成には、Cloud Audit Logs が推奨されます。

  • Cloud Audit Logs は、アクセスを継続的に追跡し、イベントの発生から数秒以内にイベントを配信します。
  • Cloud Audit Logs は使いやすいログを生成します。
  • Cloud Audit Logs では、Cloud Storage だけでなく、多くの Google Cloud サービスをモニタリングできます。
  • Cloud Audit Logs は、必要に応じてリクエストとレスポンスの詳細なログ情報を記録できます。

場合によっては、Cloud Audit Logs を使用する代わりに（またはそれに加えて）使用状況ログを使用することをおすすめします。次のような場合は使用状況ログを使用します。

  • リソースのアクセス制御で allUsers または allAuthenticatedUsers が設定されているために発生するアクセス（たとえば、静的ウェブサイトとして構成したバケット内のアセットに対するアクセス）を追跡する。
  • オブジェクトのライフサイクル管理または Autoclass 機能によって行われた変更を追跡する。
  • 認証によるブラウザでのダウンロードを使用してバケット内のオブジェクトにアクセスする予定である。
  • レイテンシの情報や、個々の HTTP リクエストのリクエスト サイズとレスポンス サイズ、URL の完全パスとクエリ パラメータをログに記録する。
  • プロジェクト内の特定のバケットのみへのアクセスを追跡する。そのため、プロジェクト内のすべてのバケットへのアクセスを追跡するデータアクセス監査ログを有効にするのを避けたい。

使用状況ログは 1 時間ごとに生成されますが、特にリクエスト率が高いバケットでは遅延が発生する可能性があります。

ストレージログと Monitoring の使い分け

通常は、ストレージログを使用するべきではありません。ストレージの使用量を測定するために推奨されるツールは Monitoring で、ストレージログにはない可視化ツールやストレージの使用量に関連する追加の指標があります。Monitoring の詳しい使用手順については、バケットのサイズを決定するのコンソールタブをご覧ください。

ログ配信を設定する

ログ配信を設定すると、指定されたバケットに使用状況ログとストレージログの両方が生成されます。バケットのログ配信を設定する手順は次のとおりです。ログの保存に使用するバケットがまだ存在しない場合は、バケットを作成します。

コマンドライン

  1. Cloud Storage にバケットの roles/storage.objectCreator ロールを付与します。

    gcloud storage buckets add-iam-policy-binding gs://example-logs-bucket --member=group:cloud-storage-analytics@google.com --role=roles/storage.objectCreator

    このロールは、Cloud Storage にグループ cloud-storage-analytics@google.com の形式で、ログを新しいオブジェクトとして作成して保存する権限を付与します。

    バケットで均一なバケットレベルのアクセスが有効になっていない限り、ログ オブジェクトにはログバケットのデフォルト オブジェクト 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":[
        "group-cloud-storage-analytics@google.com"
      ]
    }
  ]
}

    このロールは、Cloud Storage にグループ cloud-storage-analytics@google.com の形式で、ログを新しいオブジェクトとして作成して保存する権限を付与します。

    バケットで均一なバケットレベルのアクセスが有効になっていない限り、ログ オブジェクトにはログバケットのデフォルト オブジェクト ACL が適用されます。

  2. 次のリクエストを使用して、バケットのロギングを有効にします。

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

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

XML API

  1. ログを新しいオブジェクトとして作成して保存するために、バケットに対する Cloud Storage WRITE 権限を許可します。cloud-storage-analytics@google.com グループの書き込みアクセス権を付与するバケットの ACL エントリを追加する必要があります。リクエストには、新しい 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>

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

ログのダウンロード

ストレージログは 1 日に 1 回生成され、前日のストレージ使用量が記録されます。通常は 10:00 am PST までに作成されます。

使用状況ログは、モニタリングしているバケットでレポート対象アクティビティがある場合に、1 時間ごとに生成されます。使用状況ログは、通常は毎時 15 分に作成されます。

使用状況ログとストレージログを、保存されているバケットからダウンロードする最も簡単な方法は、Google Cloud コンソールまたは gcloud storage CLI を使用する方法です。使用状況ログは CSV 形式であり、その命名規則は次のようになっています。

OBJECT_PREFIX_usage_TIMESTAMP_ID_v0

同様に、ストレージログには次の命名規約が適用されます。

OBJECT_PREFIX_storage_TIMESTAMP_ID_v0

たとえば、デフォルトのオブジェクト接頭辞を使用して、example-bucket という名前のバケットの使用状況を報告し、2022 年 6 月 18 日 14:00 UTC に作成された使用状況ログ オブジェクトの名前は次のようになります。

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 を使用できます。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 を作成します。
    • スキーマデータ（.json ファイル）を、bq コマンドを実行したのと同じディレクトリから読み込みます。
    • 各ログファイルの最初の行には、列の説明が含まれているため、スキップします。

    ここに示す例では 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 など）に移動することをおすすめします。これにより、1 つのログから何度もデータをアップロードすることを避けられます。

BigQuery の機能には、BigQuery Browser Tool からもアクセスできます。ブラウザツールを使用すると、テーブル作成手順を通じてデータを読み込めます。

プログラムによるデータの読み込みなど、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 コマンドは、作業ディレクトリにファイルをコピーします。2 番目のコマンドは、ログファイルを繰り返し処理して、説明の行（最初の行）に「filename」を追加し、データ行（2 番目の行）に実際のファイル名を追加します。変更後のログファイルの例を示します。

    "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 Browser Tool を使って以下のクエリを実行することもできます。

  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 ツールの対話型シェルを終了します。

    project-name> quit

ロギングを無効にする

コマンドライン

ロギングを無効にするには、--clear-log-bucket フラグを指定して buckets update コマンドを実行します。

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 で割ります。