Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用平台記錄排解匯入主題的問題

本指南說明如何使用 Google Cloud 平台記錄，排解使用匯入主題時遇到的問題，包括 Cloud Storage 匯入主題、Azure Event Hubs 匯入主題、Amazon MSK 匯入主題和 Confluent Cloud 匯入主題。

關於平台記錄檔

支援的 Google Cloud 服務會產生專屬的平台記錄，擷取與該服務運作相關的事件和活動。這些平台記錄包含服務內發生的詳細資訊，包括成功執行的作業、錯誤、警告和其他重要事件。

平台記錄是 Cloud Logging 的一部分，兩者共用相同的功能。舉例來說，以下是平台記錄檔的重要功能清單：

記錄通常會以 JSON 物件的形式呈現，方便進一步查詢和篩選。
您可以使用控制台中的記錄功能查看平台記錄。
平台記錄也可以與 Cloud Monitoring 和其他監控工具整合，建立資訊主頁、快訊和其他監控機制。
記錄檔儲存空間會根據擷取量和保留期限產生費用。

如要進一步瞭解平台記錄檔，請參閱「Google Cloud 平台記錄檔」。

事前準備

請確認您已完成建立所用主題的先決條件：

必要角色和權限

開始前，請先確認您有「記錄」的存取權。您需要「記錄檢視器」(roles/logging.viewer) Identity and Access Management (IAM) 角色。如要進一步瞭解 Logging 存取權，請參閱「使用 IAM 控管存取權」。

以下說明如何驗證及授予 IAM 存取權：

查看目前的存取權，確認每個主體擁有的存取權。
將角色授予專案中的相關主體。

關於匯入主題擷取失敗

匯入主題可能會發生問題，導致系統無法順利擷取資料。

Cloud Storage 匯入主題

Cloud Storage 匯入主題可能會發生問題，導致資料無法成功擷取。舉例來說，使用 Cloud Storage 匯入主題時，您可能會遇到無法擷取 Cloud Storage 物件或部分物件的問題。

下列清單說明 Cloud Storage 匯入主題中，產生平台記錄檔的擷取失敗原因：

郵件大小
- 個別訊息不得超過 10 MB。如果是，系統會略過整封郵件。
- 如果您使用 Avro 或 Pub/Sub Avro 格式，Avro 區塊不得超過 16 MB。系統會略過較大的 Avro 區塊。
訊息屬性
- 訊息最多可有 100 個屬性。系統擷取訊息時，會捨棄任何額外屬性。
- 屬性鍵不得超過 256 個位元組，屬性值不得超過 1024 個位元組。如果值大於上限，系統在擷取訊息時，會從訊息中捨棄整個鍵/值組。
  
  如要進一步瞭解使用訊息鍵和屬性的相關規範，請參閱「運用屬性發布訊息」。
Avro 格式
- 請確認 Avro 物件格式正確。格式不正確會導致系統無法擷取訊息。
資料格式
- 請確認您使用的是支援的 Avro 版本。系統不會處理不支援的格式。

Azure Event Hubs、Amazon MSK 和 Confluent Cloud 匯入主題

Azure Event Hubs、Amazon MSK 和 Confluent Cloud 匯入主題可能會發生問題，導致無法成功擷取資料。

以下列出匯入主題產生平台記錄時，可能導致擷取失敗的原因：

郵件大小
- 單一訊息不得超過 10 MB。如果郵件包含這類內容，系統會略過整封郵件。
訊息屬性
- 訊息最多可有 100 個屬性。系統擷取訊息時，會捨棄任何額外屬性。
- 屬性鍵不得超過 256 個位元組，屬性值不得超過 1024 個位元組。如果值大於上限，系統在擷取訊息時，會從訊息中捨棄整個鍵/值組。
  
  如要進一步瞭解使用訊息鍵和屬性的相關規範，請參閱「運用屬性發布訊息」。

啟用平台記錄

匯入主題的平台記錄檔預設為停用。建立或更新匯入主題時，可以啟用平台記錄。如要停用平台記錄，請更新匯入主題。

建立匯入主題時啟用平台記錄

如要在建立匯入主題時啟用平台記錄，請按照下列步驟操作：

控制台

前往 Google Cloud 控制台的「Topics」(主題) 頁面。

前往「Topics」(主題)
按一下「建立主題」。
主題詳細資料頁面隨即開啟。
在「主題 ID」欄位中，輸入匯入主題的 ID。
如要進一步瞭解如何命名主題，請參閱命名規範。
選取「新增預設訂閱項目」。
選取「啟用擷取功能」。
保留其他預設設定。
按一下「建立主題」。

gcloud

在 Google Cloud 控制台中啟用 Cloud Shell。

啟用 Cloud Shell

Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。
如要啟用平台記錄，請確認 --ingestion-log-severity 旗標設為 WARNING 或較低的嚴重程度層級，例如 INFO 或 DEBUG。針對您使用的相應主題，執行 gcloud pubsub topics create 指令：
舉例來說，如要在 Cloud Storage 匯入主題上啟用平台記錄，請在 gcloud pubsub topics create 指令中加入 --ingestion-log-severity=WARNING 旗標。
```
gcloud pubsub topics create TOPIC_ID \
    --cloud-storage-ingestion-bucket=BUCKET_NAME \
    --cloud-storage-ingestion-input-format=INPUT_FORMAT \
    --ingestion-log-severity=WARNING
```

更新匯入主題時啟用平台記錄檔

如要在更新匯入主題時啟用平台記錄，請按照下列步驟操作：

控制台

前往 Google Cloud 控制台的「Topics」(主題) 頁面。

前往「主題」
按一下您使用的匯入主題 (Cloud Storage 匯入主題、Azure Event Hubs 匯入主題、 Amazon MSK 匯入主題或 Confluent Cloud 匯入主題)。
在主題詳細資料頁面中，按一下「編輯」。
選取「啟用平台記錄檔」。
按一下「Update」。

gcloud

在 Google Cloud 控制台中啟用 Cloud Shell。

啟用 Cloud Shell

Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。
如要啟用平台記錄，請確認攝取記錄嚴重程度設為 WARNING 或較低的嚴重程度層級，例如 INFO 或 DEBUG。執行 gcloud pubsub topics update 指令，並搭配所有可能的旗標，指定所用主題的設定：
- Cloud Storage 匯入主題
  - 為避免遺失 Cloud Storage 匯入主題的設定，每次更新主題時，請務必重新加入原始 create 指令中的相同值。如果遺漏任何項目，Pub/Sub 會將設定重設為預設值。
- Azure Event Hubs 匯入主題
- Amazon MSK 匯入主題
- Confluent Cloud 匯入主題
舉例來說，如要更新現有 Cloud Storage 匯入主題的記錄，請在 gcloud pubsub topics create 指令中加入 --ingestion-log-severity=WARNING 旗標，並納入所有可能的旗標值，指定 Cloud Storage 匯入主題的設定。
```
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
```

停用平台記錄檔

如要為使用的匯入主題停用平台記錄，請按照下列步驟操作：

控制台

前往 Google Cloud 控制台的「Topics」(主題) 頁面。

前往「Topics」(主題)
按一下您使用的匯入主題 (Cloud Storage 匯入主題、Azure Event Hubs 匯入主題、 Amazon MSK 匯入主題或 Confluent Cloud 匯入主題)。
在主題詳細資料頁面中，按一下「編輯」。
取消勾選「啟用平台記錄檔」。
按一下「Update」。

gcloud

在 Google Cloud 控制台中啟用 Cloud Shell。

啟用 Cloud Shell

Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。
如要停用平台記錄，請確認 ingestion-log-severity 已設為 DISABLED。執行 gcloud pubsub topics update 指令，並搭配所有可能的旗標，指定所用主題的設定：
- Cloud Storage 匯入主題
  - 為避免遺失 Cloud Storage 匯入主題的設定，請務必在每次更新主題時，重新加入原始 create 指令中的相同值。如果遺漏任何項目，Pub/Sub 會將設定重設為原始預設值。
- Azure Event Hubs 匯入主題
- Amazon MSK 匯入主題
- Confluent Cloud 匯入主題
舉例來說，如要停用現有 Cloud Storage 匯入主題的記錄，請在 gcloud pubsub topics update 指令中加入 --ingestion-log-severity=DISABLED 旗標，並加入所有可能旗標，指定 Cloud Storage 匯入主題的設定。
```
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
```

查看平台記錄

如要查看所用匯入主題的平台記錄，請按照下列步驟操作：

Google Cloud 控制台

前往 Google Cloud 控制台的「Logs Explorer」。

前往 Logs Explorer
選取 Google Cloud 專案。
視需要從「升級」Upgrade選單，將「舊版記錄檢視器」Legacy Logs Viewer切換為「Logs Explorer」Logs Explorer。
點選「Show query」(顯示查詢) 切換鈕。
如要篩選記錄，只顯示您使用的匯入主題 (Cloud Storage 匯入主題、Azure Event Hubs 匯入主題、Amazon MSK 匯入主題或 Confluent Cloud 匯入主題) 項目，請在查詢欄位中輸入 "resource.type=pubsub_topic AND severity=WARNING"，然後按一下「Run query」(執行查詢)。
在「查詢結果」窗格中，按一下「編輯時間」，即可變更要傳回結果的時間範圍。

如要進一步瞭解如何使用 Logs Explorer，請參閱「使用 Logs Explorer」。

gcloud CLI

如要使用 gcloud CLI 搜尋所用匯入主題的平台記錄，請使用 gcloud logging read 指令。

指定篩選器，將結果限制為您使用的相應匯入主題平台記錄 (Cloud Storage 匯入主題、Azure Event Hubs 匯入主題、Amazon MSK 匯入主題或 Confluent Cloud 匯入主題)。

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 物件中。

Cloud Storage

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/my-project/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": "my-project",
      "topic_id": "avro_bucket_topic"
    }
  },
  "timestamp": "2024-10-07T18:55:45.650103193Z",
  "severity": "WARNING",
  "logName": "projects/my-project/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-07T18:55:46.678221398Z"
}

記錄欄位	說明
`insertId`	記錄項目的專屬 ID。
`jsonPayload.@type`	識別事件類型。一律`type.googleapis.com/google.pubsub.v1.IngestionFailureEvent`。
`jsonPayload.cloudStorageFailure.objectGeneration`	Cloud Storage 物件的代號。
`jsonPayload.cloudStorageFailure.bucket`	包含物件的 Cloud Storage bucket。
`jsonPayload.cloudStorageFailure.objectName`	Cloud Storage 物件的名稱。
`jsonPayload.cloudStorageFailure.avroFailureReason`	包含更具體的 Avro 剖析錯誤詳細資料。這個欄位留空。
`jsonPayload.topic`	訊息預定傳送的 Pub/Sub 主題。
`jsonPayload.errorMessage`	人類可讀的錯誤訊息。
`resource.type`	資源類型。一律`pubsub_topic`。
`resource.labels.project_id`	專案 ID。 Google Cloud
`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/my-project/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": "my-project"
    }
  },
  "timestamp": "2024-10-09T14:09:07.760488386Z",
  "severity": "WARNING",
  "logName": "projects/my-project/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-09T14:09:08.483589656Z"
}

記錄欄位	說明
`insertId`	記錄項目的專屬 ID。
`jsonPayload.@type`	識別事件類型。一律`type.googleapis.com/google.pubsub.v1.IngestionFailureEvent`。
`jsonPayload.cloudStorageFailure.objectGeneration`	Cloud Storage 物件的代號。
`jsonPayload.cloudStorageFailure.bucket`	包含物件的 Cloud Storage bucket。
`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`	Cloud Logging 接收記錄項目的時間。

Amazon MSK

API 違規

  {
  "insertId": "k3breb2q",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "awsMskFailure": {
      "apiViolationReason": {},
      "clusterArn": "arn:aws:kafka:us-east-1:291552718126:cluster/cluster-ingestion/abb9faea-4070-4eb76-9c21-f98abca92eaf-2",
      "kafkaTopic": "msk-topic",
      "partitionId": "1",
      "offset": "11"
    },
    "errorMessage": "The value of an attribute in the message exceeded the maximum allowed size of 1024 bytes. Number of bytes in the value: 1025. Key: my header. Value: my very large value …",
    "topic": "projects/my-project/topics/msk-import-topic"
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "topic_id": "msk-import-topic",
      "project_id": "my-project"
    }
  },
  "timestamp": "2025-02-03T16:18:14.693357960Z",
  "severity": "WARNING",
  "logName": "projects/my-project/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2025-02-03T16:18:16.241643258Z"
}

記錄欄位	說明
`insertId`	記錄項目的專屬 ID。
`jsonPayload.@type`	識別事件類型。一律`type.googleapis.com/google.pubsub.v1.IngestionFailureEvent`。
`jsonPayload.awsMskFailure.clusterArn`	要從中擷取主題的叢集 ARN。
`jsonPayload.awsMskFailure.kafkaTopic`	要擷取資料的 Kafka 主題名稱。
`jsonPayload.awsMskFailure.partitionId`	含有無法擷取訊息的分割區 ID。
`jsonPayload.awsMskFailure.offset`	無法擷取的訊息在分區中的位移。
`jsonPayload.awsMskFailure.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`	Cloud Logging 收到記錄項目的時間。

Azure 事件中樞

API 違規

{
  "insertId": "i1fbqnb12",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "azureEventHubsFailure": {
      "apiViolationReason": {},
      "namespace": "my-namespace",
      "eventHub": "my-event-hub",
      "partitionId": "1",
      "offset": "15"
    },
    "errorMessage": "The value of an attribute in the message exceeded the maximum allowed size of 1024 bytes. Number of bytes in the value: 1025. Key: my header. Value: my very large value …",
    "topic": "projects/my-project/topics/event-hubs-import-topic"
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "topic_id": "event-hubs-import-topic",
      "project_id": "my-project"
    }
  },
  "timestamp": "2025-02-03T16:18:14.693357960Z",
  "severity": "WARNING",
  "logName": "projects/my-project/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2025-02-03T14:05:12.338211450Z"
}

記錄欄位	說明
`insertId`	記錄項目的專屬 ID。
`jsonPayload.@type`	識別事件類型。一律`type.googleapis.com/google.pubsub.v1.IngestionFailureEvent`。
`jsonPayload.azureEventHubsFailure.namespace`	包含事件中樞的命名空間，資料會從該中樞擷取。
`jsonPayload.azureEventHubsFailure.eventHub`	要從中擷取的事件中樞名稱。
`jsonPayload.azureEventHubsFailure.partitionId`	分區 ID，該分區含有無法擷取的訊息。
`jsonPayload.azureEventHubsFailure.offset`	無法擷取的訊息在分區中的位移。
`jsonPayload.azureEventHubsFailure.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`	Cloud Logging 接收記錄項目的時間。

Confluent Cloud

文字失敗

{
  "insertId": "i1fbqnb14",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "confluentCloudFailure": {
      "apiViolationReason": {},
      "clusterId": "lma-1x18ae",
      "kafkaTopic": "confluent-topic",
      "partitionId": "1",
      "offset": "19"
    },
    "errorMessage": "The value of an attribute in the message exceeded the maximum allowed size of 1024 bytes. Number of bytes in the value: 1025. Key: my header. Value: my very large value …",
    "topic": "projects/my-project/topics/confluent-import-topic"
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "topic_id": "confluent-import-topic",
      "project_id": "my-project"
    }
  },
  "timestamp": "2025-02-03T16:18:14.693357960Z",
  "severity": "WARNING",
  "logName": "projects/my-project/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2025-02-03T17:03:11.428221440Z"
}

記錄欄位	說明
`insertId`	記錄項目的專屬 ID。
`jsonPayload.@type`	識別事件類型。一律`type.googleapis.com/google.pubsub.v1.IngestionFailureEvent`。
`jsonPayload.confluentCloudFailure.clusterId`	內含要擷取主題的叢集 ID。
`jsonPayload.confluentCloudFailure.kafkaTopic`	要擷取資料的 Kafka 主題名稱。
`jsonPayload.confluentCloudFailure.partitionId`	含有無法擷取訊息的分割區 ID。
`jsonPayload.confluentCloudFailure.offset`	無法擷取的訊息在分區中的位移。
`jsonPayload.confluentCloudFailure.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`	Cloud Logging 接收記錄項目的時間。

Apache Kafka® 是 The Apache Software Foundation 或其分支機構在美國和/或其他國家/地區的註冊商標。

使用平台記錄排解匯入主題的問題 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

關於平台記錄檔

事前準備

必要角色和權限

關於匯入主題擷取失敗

Cloud Storage 匯入主題

Azure Event Hubs、Amazon MSK 和 Confluent Cloud 匯入主題

啟用平台記錄

建立匯入主題時啟用平台記錄

控制台

gcloud

更新匯入主題時啟用平台記錄檔

控制台

gcloud

停用平台記錄檔

控制台

gcloud

查看平台記錄

Google Cloud 控制台

gcloud CLI

Cloud Logging API

查看及瞭解平台記錄格式

Cloud Storage

Avro 失敗

文字失敗

Amazon MSK

API 違規

Azure 事件中樞

API 違規

Confluent Cloud

文字失敗

使用平台記錄排解匯入主題的問題