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

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

關於平台記錄檔

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

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

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

事前準備

請確認您已完成所用主題的必要條件：

必要角色和權限

開始前，請先確認您有權存取記錄。 您需要 Logs Viewer (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 物件格式正確。格式不正確 會導致系統無法擷取訊息。

  • 資料格式

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

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

以下列出匯入主題中，導致擷取作業失敗的原因 (會產生平台記錄)：

  • 郵件大小

    • 單一訊息不得超過 10 MB。如果是，系統會略過整封郵件。

  • 訊息屬性

    • 訊息最多可有 100 個屬性。系統擷取訊息時，會捨棄任何額外屬性。

    • 屬性鍵大小不可超過 256 個位元組，屬性值大小不可超過 1024 個位元組。如果值大於上限，系統在擷取訊息時，會從訊息中捨棄整個鍵值組。

      如要進一步瞭解訊息鍵和屬性的使用規範，請參閱「運用屬性發布訊息」。

啟用平台記錄

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

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

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

控制台

  1. 前往 Trusted Cloud 控制台的「主題」頁面。

    前往「主題」

  2. 按一下「建立主題」。

    主題詳細資料頁面隨即開啟。

  3. 在「主題 ID」欄位中，輸入匯入主題的 ID。

    如要進一步瞭解如何為主題命名，請參閱命名規範。

  4. 選取「新增預設訂閱項目」。

  5. 選取「啟用擷取功能」。

  6. 保留其他預設設定。
  7. 按一下「建立主題」。

gcloud

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

    Activate Cloud Shell

    At the bottom of the Trusted 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 或較低的嚴重程度層級，例如 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

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

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

控制台

  1. 前往 Trusted Cloud 控制台的「主題」頁面。

    前往「主題」

  2. 按一下您使用的匯入主題 (Cloud Storage 匯入主題、Azure Event Hubs 匯入主題、Amazon MSK 匯入主題或 Confluent Cloud 匯入主題)。

  3. 在主題詳細資料頁面中，按一下「編輯」。

  4. 選取「啟用平台記錄檔」。

  5. 按一下「更新」。

gcloud

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

    Activate Cloud Shell

    At the bottom of the Trusted 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 或較低的嚴重程度層級，例如 INFO 或 DEBUG。 執行 gcloud pubsub topics update 指令，並加上所有可能的旗標，指定所用主題的設定：

    舉例來說，如要更新現有 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

停用平台記錄檔

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

控制台

  1. 前往 Trusted Cloud 控制台的「主題」頁面。

    前往「主題」

  2. 按一下您使用的匯入主題 (Cloud Storage 匯入主題、Azure Event Hubs 匯入主題、Amazon MSK 匯入主題或 Confluent Cloud 匯入主題)。

  3. 在主題詳細資料頁面中，按一下「編輯」。

  4. 清除「啟用平台記錄檔」。

  5. 按一下「更新」。

gcloud

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

    Activate Cloud Shell

    At the bottom of the Trusted 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. 如要停用平台記錄，請確認攝取記錄嚴重程度設為 DISABLED。 執行 gcloud pubsub topics update 指令，並加上所有可能的旗標，指定所用主題的設定：

    舉例來說，如要停用現有 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

查看平台記錄

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

Trusted Cloud 控制台

  1. 前往 Trusted Cloud 控制台的「Logs Explorer」頁面。

    前往記錄檔探索工具

  2. 選取 Trusted Cloud 專案。

  3. 如有需要，請從「Upgrade」(升級) 選單，將「Legacy Logs Viewer」(舊版記錄檢視器) 切換為「Logs Explorer」(記錄檔探索工具)。

  4. 按一下「顯示查詢」切換按鈕。

  5. 如要篩選記錄檔，只顯示您使用的各個匯入主題 (Cloud Storage 匯入主題、Azure Event Hubs 匯入主題、Amazon MSK 匯入主題或 Confluent Cloud 匯入主題) 的項目，請在查詢欄位中輸入 "resource.type=pubsub_topic AND severity=WARNING"，然後按一下「執行查詢」。

  6. 在「查詢結果」窗格中，按一下「編輯時間」，即可變更要傳回結果的時間範圍。

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

gcloud CLI

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

指定篩選條件，將結果限制為您使用的各個匯入主題的平台記錄 (Cloud Storage 匯入主題、Azure 事件中樞匯入主題、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 值區。
jsonPayload.cloudStorageFailure.objectName Cloud Storage 物件的名稱。
jsonPayload.cloudStorageFailure.avroFailureReason 包含更具體的 Avro 剖析錯誤詳細資料。這個欄位留空。
jsonPayload.topic 訊息預定傳送的 Pub/Sub 主題。
jsonPayload.errorMessage 使用者可理解的錯誤訊息。
resource.type 資源類型。一律 pubsub_topic。
resource.labels.project_id 專案 ID。 Trusted 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 值區。
jsonPayload.cloudStorageFailure.objectName Cloud Storage 物件的名稱。
jsonPayload.cloudStorageFailure.apiViolationReason 包含 API 違規事項的詳細資料。這個欄位留空。
jsonPayload.topic Pub/Sub 主題。
jsonPayload.errorMessage 使用者可理解的訊息。
resource.type 資源類型，一律為 pubsub_topic。
resource.labels.project_id Trusted 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 Trusted 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 Trusted 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 或其關聯企業在美國與/或其他國家/地區的註冊商標。