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

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

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

關於平台記錄檔

支援的 Google Cloud 服務會產生自己的平台記錄集，擷取與該服務運作相關的事件和活動。這些平台記錄檔包含服務內發生事件的詳細資訊，包括成功的作業、錯誤、警告和其他值得注意的事件。

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

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

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

事前準備

請確認您已完成建立所用主題的前置作業：

必要角色和權限

開始前，請確認您有權存取「記錄」。您必須具備 Logs Viewer (roles/logging.viewer) Identity and Access Management (IAM) 角色。如要進一步瞭解 Logging 存取權，請參閱「使用身分與存取權管理功能控管存取權」。

以下說明如何驗證及授予 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 事件中樞、Amazon MSK 和 Confluent Cloud 匯入主題

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

下列清單說明匯入主題產生平台記錄時，擷取內容失敗的原因：

郵件大小
- 個別訊息的大小不得超過 10 MB。如果是，系統會略過整個訊息。
訊息屬性
- 訊息屬性數量上限為 100 項。系統會在擷取訊息時捨棄任何額外屬性。
- 屬性鍵的大小不得超過 256 個位元組，值的大小不得超過 1024 個位元組。如果值大於最大值，系統在擷取訊息時，就會從訊息中捨棄整個鍵/值組。
  
  如要進一步瞭解使用訊息鍵和屬性的規範，請參閱「運用屬性發布訊息」。

啟用平台記錄

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

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

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

控制台

前往 Google Cloud 控制台的「Topics」頁面。

前往「主題」
按一下「建立主題」。
主題詳細資料頁面隨即開啟。
在「主題 ID」欄位中，輸入匯入主題的 ID。
如要進一步瞭解主題命名方式，請參閱命名規範。
選取「Add a default subscription」。
選取「啟用擷取」。
保留其他預設設定。
按一下「建立主題」。

gcloud

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.
如要啟用平台記錄，請確認 --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

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.
如要啟用平台記錄，請確認 ingestion-log-severity 已設為 WARNING 或較低的嚴重性層級，例如 INFO 或 DEBUG。執行 gcloud pubsub topics update 指令，並加上所有可能的標記，為您使用的相關主題指定設定：
- Cloud Storage 匯入主題
  - 為避免遺失 Cloud Storage 匯入主題的設定，請務必在每次更新主題時，重新加入原始 create 指令中的值。如果您省略某些項目，Pub/Sub 會將設定重設為預設值。
- Azure 事件中樞匯入主題
- 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」頁面。

前往「主題」
按一下您要使用的匯入主題 (Cloud Storage 匯入主題、Azure Event Hubs 匯入主題、Amazon MSK 匯入主題或 Confluent Cloud 匯入主題)。
在主題詳細資料頁面中，按一下「編輯」。
清除「Enable platform logs」。
按一下 [Update]。

gcloud

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.
如要停用平台記錄，請確認 ingestion-log-severity 設為 DISABLED。執行 gcloud pubsub topics update 指令，並加上所有可能的標記，為您使用的相關主題指定設定：
- Cloud Storage 匯入主題
  - 為避免遺失 Cloud Storage 匯入主題的設定，請務必在每次更新主題時，重新加入原始 create 指令中的值。如果您未提供任何內容，Pub/Sub 會將設定重設為原始預設值。
- Azure 事件中樞匯入主題
- 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」。
按一下「顯示查詢」切換鈕。
如要篩選記錄檔，只顯示您使用的匯入主題 (Cloud Storage 匯入主題、Azure Event Hubs 匯入主題、Amazon MSK 匯入主題或 Confluent Cloud 匯入主題) 的項目，請在查詢欄位中輸入 resource.type="resource.type=pubsub_topic AND severity=WARNING"，然後按一下「執行查詢」。
在「查詢結果」窗格中，按一下「編輯時間」，變更傳回結果的時間範圍。

如要進一步瞭解如何使用記錄檔探索工具，請參閱「使用記錄檔探索工具」。

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": &quot;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 值區。
`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/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&quot;: "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 值區。
`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",
      &quot;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",
      &quot;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",
      &quot;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® 是 Apache 軟體基金會 (Apache Software Foundation) 或其關聯企業在美國與/或其他國家/地區的註冊商標。

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

關於平台記錄檔

事前準備

必要角色和權限

關於匯入主題擷取失敗

Cloud Storage 匯入主題

Azure 事件中樞、Amazon MSK 和 Confluent Cloud 匯入主題

啟用平台記錄

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

控制台

gcloud

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

控制台

gcloud

停用平台記錄檔

控制台

gcloud

查看平台記錄檔

Google Cloud 控制台

gcloud CLI

Cloud Logging API

查看及瞭解平台記錄格式

Cloud Storage

Avro 失敗

文字失敗

Amazon MSK

API 違規

Azure 事件中樞

API 違規

Confluent Cloud

文字失敗

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