プラットフォーム ログを使用して Cloud Storage インポート トピックのトラブルシューティングを行う

このガイドでは、Cloud Storage インポート トピックを使用してデータを取り込むときに、Google Cloud Platform ログを使用して問題をトラブルシューティングする方法について説明します。

注: Amazon Kinesis Data Streams インポート トピックのプラットフォーム ログを有効または無効にできます。ただし、Kinesis ストリームデータは常に Pub/Sub のメッセージ要件と互換性があり、パブリッシュできます。したがって、ログは書き込まれません。

Cloud Storage インポート トピックの取り込みエラーについて

Cloud Storage インポート トピックで、データが正常に取り込まれない問題が発生することがあります。たとえば、Cloud Storage インポート トピックを使用すると、Cloud Storage オブジェクトまたはオブジェクトの一部を取り込む際に問題が発生することがあります。

次のリストに、プラットフォーム ログを生成する Cloud Storage インポート トピックで取り込みに失敗する理由を示します。

• メッセージのサイズ

  • 個々のメッセージのサイズは 10 MB 以下にする必要があります。一致した場合、メッセージ全体がスキップされます。

  • Avro 形式または Pub/Sub Avro 形式を使用している場合、メッセージ ブロックのサイズは 16 MB 以下にする必要があります。サイズの大きいメッセージ ブロックはスキップされます。

• メッセージ属性

  • メッセージに設定できる属性は最大 100 個です。メッセージの取り込み時に、余分な属性は破棄されます。

  • 属性キーは 256 バイト以下にする必要があります。値は 1,024 バイト以下にする必要があります。サイズの大きいキーまたは値は、取り込み時にメッセージから削除されます。

    メッセージ キーと属性の使用に関するガイドラインの詳細については、属性を使用してメッセージをパブリッシュするをご覧ください。

• Avro のフォーマット

  • Avro オブジェクトの形式が正しいことを確認します。形式が正しくないと、メッセージは取り込まれません。

• データ形式

  • サポートされている Avro バージョンを使用していることを確認します。サポートされていない形式は処理されません。

プラットフォーム ログについて

サポートされている Google Cloud サービスは、独自のプラットフォーム ログセットを生成し、そのサービスのオペレーションに関連するイベントとアクティビティをキャプチャします。これらのプラットフォーム ログには、オペレーションの成功、エラー、警告、その他の注目すべきイベントなど、サービス内で発生した事象に関する詳細情報が含まれます。

プラットフォーム ログは Cloud Logging の一部であり、同じ機能を共有します。たとえば、プラットフォーム ログの重要な機能のリストは次のとおりです。

• 通常、ログは JSON オブジェクトとして構造化され、さらにクエリとフィルタリングが可能です。

• プラットフォーム ログを表示するには、コンソールの Logging を使用します。

• プラットフォーム ログを Cloud Monitoring やその他のモニタリング ツールと統合して、ダッシュボード、アラート、その他のモニタリング メカニズムを作成することもできます。

• ログ ストレージには、取り込まれた量と保持期間に基づく費用が発生します。

プラットフォームのログの詳細については、Google Cloud プラットフォーム ログをご覧ください。

プラットフォーム ログを使用するのに必要なロールと権限

始める前に、Logging にアクセスできることを確認してください。ログ閲覧者 (roles/logging.viewer) Identity and Access Management（IAM）ロールが必要です。Logging のアクセスの詳細については、IAM によるアクセス制御をご覧ください。

以下では、IAM アクセス権を確認して付与する方法を説明します。

• 現在のアクセス権を表示して、各プリンシパルのアクセス権を確認します。

• プロジェクトの関連するプリンシパルにロールを付与します。

プラットフォームのログを有効にする

インポート トピックでは、プラットフォーム ログはデフォルトで無効になっています。プラットフォーム ログは、Cloud Storage インポート トピックの作成時または更新時に有効にできます。

プラットフォーム ログを無効にするには、Cloud Storage インポート トピックを更新します。

Cloud Storage インポート トピックの作成時にプラットフォーム ログを有効にする

Cloud Storage インポート トピックの作成の前提条件を満たしていることを確認します。

プラットフォーム ログを有効にして Cloud Storage インポート トピックを作成する手順は次のとおりです。

Console

1. Google Cloud コンソールの トピック ページに移動します。

   [トピック] に移動

2. [トピックを作成] をクリックします。

   トピックの詳細ページが開きます。

3. [トピック ID] フィールドに、Cloud Storage インポート トピックの ID を入力します。

   トピックの命名の詳細については、命名ガイドラインをご覧ください。

4. [デフォルトのサブスクリプションを追加する] を選択します。

5. [取り込みを有効にする] を選択します。

6. Cloud Storage インポート トピックを作成するの手順に沿って、取り込みのオプションを指定します。
7. [プラットフォーム ログを有効にする] を選択します。
8. 他のデフォルト設定はそのままにします。
9. [トピックを作成] をクリックします。

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. プラットフォーム ログを有効にするには、--ingestion-log-severity フラグが WARNING 以上に設定されていることを確認します。 gcloud pubsub topics create コマンドを実行します。

   gcloud pubsub topics create TOPIC_ID\
       --cloud-storage-ingestion-bucket=BUCKET_NAME\
       --cloud-storage-ingestion-input-format=INPUT_FORMAT\
       --ingestion-log-severity=WARNING

   次のように置き換えます。

   • TOPIC_ID: トピックの名前または ID。

   • BUCKET_NAME: 既存のバケットの名前を指定します。例: prod_bucketバケット名にプロジェクト ID を含めてはいけません。バケットを作成するには、バケットを作成するをご覧ください。

   • INPUT_FORMAT: 取り込まれるオブジェクトの形式を指定します。値は text、avro、pubsub_avro です。これらのオプションの詳細については、入力形式をご覧ください。

問題が発生した場合は、Cloud Storage インポート トピックのトラブルシューティングをご覧ください。

Cloud Storage インポート トピックを更新するときにプラットフォーム ログを有効にする

次の手順を行います。

Console

1. Google Cloud コンソールの トピック ページに移動します。

   [トピック] に移動

2. Cloud Storage インポート トピックをクリックします。

3. [トピックの詳細] ページで、[編集] をクリックします。

4. [プラットフォーム ログを有効にする] を選択します。

5. [更新] をクリックします。

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. インポート トピックの設定が失われないようにするには、トピックを更新するたびにすべての設定を含めてください。値を指定しない場合は、Pub/Sub によって設定が元のデフォルト値にリセットされます。

   プラットフォーム ログを有効にするには、ingestion-log-severity が WARNING に設定されていることを確認します。次のサンプルに記載されているフラグをすべて指定して、gcloud pubsub topics update コマンドを実行します。

   gcloud pubsub topics update TOPIC_ID \
       --cloud-storage-ingestion-bucket=BUCKET_NAME\
       --cloud-storage-ingestion-input-format=INPUT_FORMAT\
       --cloud-storage-ingestion-text-delimiter=TEXT_DELIMITER\
       --cloud-storage-ingestion-minimum-object-create-time=MINIMUM_OBJECT_CREATE_TIME\
       --cloud-storage-ingestion-match-glob=MATCH_GLOB
       --ingestion-log-severity=WARNING

   次のように置き換えます。

   • TOPIC_ID はトピック ID または名前です。このフィールドは更新できません。

   • BUCKET_NAME: 既存のバケットの名前を指定します。例: prod_bucketバケット名にプロジェクト ID を含めてはいけません。

   • INPUT_FORMAT: 取り込まれるオブジェクトの形式を指定します。値は text、avro、pubsub_avro です。これらのオプションの詳細については、入力形式をご覧ください。

   • TEXT_DELIMITER: テキスト オブジェクトを Pub/Sub メッセージに分割する区切り文字を指定します。これは 1 文字にする必要があります。また、INPUT_FORMAT が text の場合にのみ設定する必要があります。デフォルトは改行文字（\n）です。

     gcloud CLI を使用して区切り文字を指定する場合は、改行 \n などの特殊文字の処理に注意してください。区切り文字が正しく解釈されるように、形式 '\n' を使用します。引用符やエスケープなしで \n を使用すると、区切り文字が "n" になります。

   • MINIMUM_OBJECT_CREATE_TIME: オブジェクトが取り込まれるために作成された最小時間を指定します。UTC の YYYY-MM-DDThh:mm:ssZ 形式で指定します。例: 2024-10-14T08:30:30Z

     0001-01-01T00:00:00Z～9999-12-31T23:59:59Z までの過去または未来の日付はすべて有効です。

   • MATCH_GLOB: オブジェクトを取り込むために一致させる glob パターンを指定します。gcloud CLI を使用している場合、* 文字を含むマッチ グロブでは、* 文字を \*\*.txt 形式でエスケープするか、マッチ グロブ全体を引用符 "**.txt" または '**.txt' で囲む必要があります。glob パターンでサポートされている構文については、 Cloud Storage のドキュメントをご覧ください。

プラットフォームのログを無効にする

次の手順を行います。

Console

1. Google Cloud コンソールの トピック ページに移動します。

   [トピック] に移動

2. Cloud Storage インポート トピックをクリックします。

3. [トピックの詳細] ページで、[編集] をクリックします。

4. [プラットフォーム ログを有効にする] をオフにします。

5. [更新] をクリックします。

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. インポート トピックの設定が失われないようにするには、トピックを更新するたびにすべての設定を含めてください。値を指定しない場合は、Pub/Sub によって設定が元のデフォルト値にリセットされます。

   プラットフォーム ログを無効にするには、ingestion-log-severity が DISABLED に設定されていることを確認します。次のサンプルに記載されているフラグをすべて指定して、gcloud pubsub topics update コマンドを実行します。

   gcloud pubsub topics update TOPIC_ID \
       --cloud-storage-ingestion-bucket=BUCKET_NAME\
       --cloud-storage-ingestion-input-format=INPUT_FORMAT\
       --cloud-storage-ingestion-text-delimiter=TEXT_DELIMITER\
       --cloud-storage-ingestion-minimum-object-create-time=MINIMUM_OBJECT_CREATE_TIME\
       --cloud-storage-ingestion-match-glob=MATCH_GLOB
       --ingestion-log-severity=DISABLED

   次のように置き換えます。

   • TOPIC_ID はトピック ID または名前です。このフィールドは更新できません。

   • BUCKET_NAME: 既存のバケットの名前を指定します。例: prod_bucketバケット名にプロジェクト ID を含めてはいけません。

   • INPUT_FORMAT: 取り込まれるオブジェクトの形式を指定します。値は text、avro、pubsub_avro です。これらのオプションの詳細については、入力形式をご覧ください。

   • TEXT_DELIMITER: テキスト オブジェクトを Pub/Sub メッセージに分割する区切り文字を指定します。これは 1 文字にする必要があります。また、INPUT_FORMAT が text の場合にのみ設定する必要があります。デフォルトは改行文字（\n）です。

     gcloud CLI を使用して区切り文字を指定する場合は、改行 \n などの特殊文字の処理に注意してください。区切り文字が正しく解釈されるように、形式 '\n' を使用します。引用符やエスケープなしで \n を使用すると、区切り文字が "n" になります。

   • MINIMUM_OBJECT_CREATE_TIME: オブジェクトが取り込まれるために作成された最小時間を指定します。UTC の YYYY-MM-DDThh:mm:ssZ 形式で指定します。例: 2024-10-14T08:30:30Z

     0001-01-01T00:00:00Z～9999-12-31T23:59:59Z までの過去または未来の日付はすべて有効です。

   • MATCH_GLOB: オブジェクトを取り込むために一致させる glob パターンを指定します。gcloud CLI を使用している場合、* 文字を含むマッチ グロブでは、* 文字を \*\*.txt 形式でエスケープするか、マッチ グロブ全体を引用符 "**.txt" または '**.txt' で囲む必要があります。glob パターンでサポートされている構文については、 Cloud Storage のドキュメントをご覧ください。

プラットフォーム ログを表示する

Cloud Storage インポート トピックのプラットフォーム ログを表示する手順は次のとおりです。

Google Cloud コンソール

1. Google Cloud コンソールで、[ログ エクスプローラ] に移動します。

   [ログ エクスプローラ] に移動

2. Google Cloud プロジェクトを選択します。

3. 必要に応じて、[アップグレード] メニューで [以前のログビューア] から [ログ エクスプローラ] に切り替えます。

4. ログをフィルタリングして Cloud Storage インポート トピックのエントリのみを表示するには、クエリ フィールドに「resource.type="resource.type=pubsub_topic AND severity=WARNING」と入力して [クエリを実行] をクリックします。

5. [クエリ結果] ペインで [日時を編集する] をクリックし、結果を返す期間を変更します。

ログ エクスプローラの使用方法については、ログ エクスプローラの使用をご覧ください。

gcloud CLI

gcloud CLI を使用して Cloud Storage インポート トピックのプラットフォーム ログを検索するには、gcloud logging read コマンドを使用します。

フィルタを指定して、Cloud Storage インポート トピックのプラットフォーム ログに結果を限定します。

gcloud logging read "resource.type=pubsub_topic AND severity=WARNING"

Cloud Logging API

entries.list Cloud Logging API メソッドを使用します。

Cloud Storage インポート トピックのプラットフォーム ログのみを含むように結果をフィルタするには、filter フィールドを使用します。サンプル JSON リクエスト オブジェクトを次に示します。

{
"resourceNames":
  [
    "projects/my-project-name"
  ],
  "orderBy": "timestamp desc",
  "filter": "resource.type=\"pubsub_topic\" AND severity=WARNING"
}

プラットフォーム ログの形式を表示して理解する

次のセクションでは、プラットフォーム ログの例と、プラットフォーム ログのフィールドについて説明します。

プラットフォーム ログ固有のフィールドはすべて、jsonPayload オブジェクトに格納されます。

Avro の障害

{
  "insertId": "1xnzx8md4768",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "cloudStorageFailure": {
      "objectGeneration": "1661148924738910",
      "bucket": "bucket_in_avro_format",
      "objectName": "counts/taxi-2022-08-15T06:10:00.000Z-2022-08-15T06:15:00.000Z-pane-0-last-00-of-01",
      "avroFailureReason": {}
    },
    "topic": "projects/interpod-p2-management/topics/avro_bucket_topic",
    "errorMessage": "Unable to parse the header of the object. The object won't be ingested."
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "project_id": "interpod-p2-management",
      "topic_id": "avro_bucket_topic"
    }
  },
  "timestamp": "2024-10-07T18:55:45.650103193Z",
  "severity": "WARNING",
  "logName": "projects/interpod-p2-management/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-07T18:55:46.678221398Z"
}

ログフィールド	説明
insertId	ログエントリの一意の識別子。
jsonPayload.@type	イベントタイプを識別します。常に type.googleapis.com/google.pubsub.v1.IngestionFailureEvent です。
jsonPayload.cloudStorageFailure.objectGeneration	Cloud Storage オブジェクトの世代番号。
jsonPayload.cloudStorageFailure.bucket	オブジェクトを含む Cloud Storage バケット。
jsonPayload.cloudStorageFailure.objectName	Cloud Storage オブジェクトの名前。
jsonPayload.cloudStorageFailure.avroFailureReason	Avro 解析エラーの詳細が含まれます。このフィールドは空白のままにします。
jsonPayload.topic	メッセージの宛先となる Pub/Sub トピック。
jsonPayload.errorMessage	人が読めるエラー メッセージ。
resource.type	リソースの型。 常に pubsub_topic です。
resource.labels.project_id	Google Cloud プロジェクト ID。
resource.labels.topic_id	Pub/Sub トピック ID。
timestamp	ログエントリの生成タイムスタンプ。
severity	重大度レベル（WARNING）。
logName	ログの名前。
receiveTimestamp	ログエントリの受信タイムスタンプ。

テキストエラー

{
  "insertId": "1kc4puoag",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "cloudStorageFailure": {
      "bucket": "bucket_in_text_format",
      "apiViolationReason": {},
      "objectName": "counts/taxi-2022-08-15T06:10:00.000Z-2022-08-15T06:15:00.000Z-pane-0-last-00-of-01",
      "objectGeneration": "1727990048026758"
    },
    "topic": "projects/interpod-p2-management/topics/large_text_bucket_topic",
    "errorMessage": "The message has exceeded the maximum allowed size of 10000000 bytes. The message won't be published."
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "topic_id": "large_text_bucket_topic",
      "project_id": "interpod-p2-management"
    }
  },
  "timestamp": "2024-10-09T14:09:07.760488386Z",
  "severity": "WARNING",
  "logName": "projects/interpod-p2-management/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-09T14:09:08.483589656Z"
}

ログフィールド	説明
insertId	ログエントリの一意の識別子。
jsonPayload.@type	イベントタイプを識別します。常に type.googleapis.com/google.pubsub.v1.IngestionFailureEvent です。
jsonPayload.cloudStorageFailure.objectGeneration	Cloud Storage オブジェクトの世代番号。
jsonPayload.cloudStorageFailure.bucket	オブジェクトを含む Cloud Storage バケット。
jsonPayload.cloudStorageFailure.objectName	Cloud Storage オブジェクトの名前。
jsonPayload.cloudStorageFailure.apiViolationReason	API 違反の詳細が含まれます。このフィールドは空白のままにします。
jsonPayload.topic	Pub/Sub トピック。
jsonPayload.errorMessage	人が読めるメッセージ。
resource.type	リソースタイプ（常に pubsub_topic）。
resource.labels.project_id	Google Cloud プロジェクト ID。
resource.labels.topic_id	Pub/Sub トピック ID。
timestamp	ログエントリの生成タイムスタンプ。
severity	重大度レベル（WARNING）。
logName	ログの名前。
receiveTimestamp	Logging がログエントリを受信した時刻。