使用平台日志排查导入主题的问题

本指南介绍了如何使用 Google Cloud 平台日志排查使用导入主题时出现的问题，包括 Cloud Storage 导入主题、Azure Event Hubs 导入主题、Amazon MSK 导入主题和 Confluent Cloud 导入主题。

注意： 您可以为 Amazon Kinesis Data Streams 导入主题启用或停用平台日志。不过，Kinesis 流数据始终与 Pub/Sub 的消息要求兼容，并且可以发布。因此，系统不会写入任何日志。

平台日志简介

受支持的 Google Cloud 服务会生成自己的一组平台日志，捕获与该服务操作相关的事件和活动。这些平台日志包含有关服务中发生的情况的详细信息，包括成功的操作、错误、警告和其他值得注意的事件。

平台日志是 Cloud Logging 的一部分，具有相同的功能。例如，以下是平台日志的重要功能列表：

• 日志通常采用 JSON 对象的结构，以便进行进一步的查询和过滤。

• 您可以使用控制台中的日志记录功能查看平台日志。

• 平台日志还可以与 Cloud Monitoring 和其他监控工具集成，以创建信息中心、提醒和其他监控机制。

• 日志存储费用取决于提取量和保留期限。

如需详细了解平台日志，请参阅 Google Cloud Platform 日志。

准备工作

确保您已满足创建所用主题的前提条件：

• “Cloud Storage 导入”主题
• “Azure 事件中心导入”主题
• Amazon MSK 导入主题
• “Confluent Cloud 导入”主题

所需的角色和权限

在开始之前，请验证您是否有权访问 Logging。 您需要拥有 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 对象格式正确无误。格式不正确会导致消息无法提取。

• 数据格式

  • 确保您使用的是受支持的 Avro 版本。系统不会处理不受支持的格式。

Azure Event Hubs、Amazon MSK 和 Confluent Cloud 导入主题

导入 Azure Event Hubs、Amazon MSK 和 Confluent Cloud 主题时可能会遇到导致数据无法成功提取的问题。

下表介绍了生成平台日志的导入主题中提取失败的原因：

• 邮件大小

  • 单个邮件的大小不得超过 10 MB。如果存在，系统会跳过整个消息。

• 消息特性

  • 消息最多可以包含 100 个属性。在提取消息时，系统会丢弃任何额外的属性。

  • 属性键不能大于 256 个字节，值不能大于 1024 个字节。如果值大于最大大小，系统会在提取消息时从消息中删除整个键值对。

    如需详细了解使用消息键和属性的指南，请参阅使用属性发布消息。

启用平台日志

默认情况下，平台日志会针对导入主题停用。您可以在创建或更新导入主题时启用平台日志。如需停用平台日志，请更新导入主题。

在创建导入主题时启用平台日志

如需在创建导入主题时启用平台日志，请执行以下操作：

控制台

1. 在 Google Cloud 控制台中，前往主题页面。

   转到“主题”

2. 点击创建主题。

   系统随即会打开主题详情页面。

3. 在主题 ID 字段中，输入导入主题的 ID。

   如需详细了解如何命名主题，请参阅命名准则。

4. 选择添加默认订阅。

5. 选择启用提取。

6. 保留其他默认设置。
7. 点击创建主题。

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 或更低的严重级别（例如 INFO 或 DEBUG）。针对您使用的相应主题运行 gcloud pubsub topics create 命令：

   • “Cloud Storage 导入”主题
   • “Azure 事件中心导入”主题
   • Amazon MSK 导入主题
   • “Confluent Cloud 导入”主题

   例如，如需为 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. 在 Google Cloud 控制台中，前往主题页面。

   转到“主题”

2. 点击您使用的相应导入主题（Cloud Storage 导入主题、Azure Event Hubs 导入主题、Amazon MSK 导入主题或 Confluent Cloud 导入主题）。

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. 如需启用平台日志，请确保将 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

停用平台日志

如需为您使用的相应导入主题停用平台日志，请执行以下操作：

控制台

1. 在 Google Cloud 控制台中，前往主题页面。

   转到“主题”

2. 点击您使用的相应导入主题（Cloud Storage 导入主题、Azure Event Hubs 导入主题、Amazon MSK 导入主题或 Confluent Cloud 导入主题）。

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. 如需停用平台日志，请确保将 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 控制台

1. 在 Google Cloud 控制台中，打开日志浏览器。

   转到日志浏览器

2. 选择 Google Cloud 项目。

3. 根据需要，在升级菜单中，从旧版日志查看器切换到日志浏览器。

4. 点击显示查询切换开关。

5. 如需过滤日志以仅显示您正在使用的相应导入主题（Cloud Storage 导入主题、Azure Event Hubs 导入主题、Amazon MSK 导入主题或 Confluent Cloud 导入主题）的条目，请在查询字段中输入 resource.type="resource.type=pubsub_topic AND severity=WARNING"，然后点击运行查询。

6. 在查询结果窗格中，点击修改时间以更改返回结果的时间段。

如需详细了解如何使用日志浏览器，请参阅使用日志浏览器。

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	日志条目的唯一标识符。
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": "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	日志条目的唯一标识符。
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",
      "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	日志条目的唯一标识符。
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	日志条目的唯一标识符。
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	日志条目的唯一标识符。
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 Software Foundation 或其关联公司在美国和/或其他国家/地区的注册商标。