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

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

平台日志简介

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

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

日志通常以 JSON 对象的形式结构化，以便进行进一步的查询和过滤。
您可以使用控制台中的 Logging 查看平台日志。
平台日志还可以与 Cloud Monitoring 和其他监控工具集成，以创建信息中心、提醒和其他监控机制。
日志存储会产生费用，具体取决于提取量和保留期限。

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

准备工作

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

所需的角色和权限

在开始之前，请验证您是否有权访问 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 事件中心、Amazon MSK 和 Confluent Cloud 导入主题

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

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

邮件大小
- 单个消息的大小不得超过 10 MB。如果存在，则跳过整个消息。
消息特性
- 消息最多可包含 100 个属性。在提取消息时，系统会舍弃所有额外的属性。
- 属性键不能大于 256 个字节，属性值不能大于 1024 个字节。如果该值大于最大大小，则在提取消息时，整个键值对都会从消息中舍弃。
  
  如需详细了解使用消息键和属性的指南，请参阅使用属性发布消息。

启用平台日志

对于导入主题，平台日志默认处于停用状态。您可以在创建或更新导入主题时启用平台日志。如需停用平台日志，请更新导入主题。

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

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

控制台

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

转到“主题”
点击创建主题。
系统会打开主题详情页面。
在主题 ID 字段中，输入导入主题的 ID。
如需详细了解如何命名主题，请参阅命名准则。
选择添加默认订阅。
选择启用提取。
保留其他默认设置。
点击创建主题。

gcloud

在 Google Cloud 控制台中，激活 Cloud Shell。

激活 Cloud Shell

Cloud Shell 会话随即会在 Google Cloud 控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。
如需启用平台日志，请确保 --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 控制台中，前往主题页面。

转到“主题”
点击您使用的相应导入主题（Cloud Storage 导入主题、Azure Event Hubs 导入主题、Amazon MSK 导入主题或 Confluent Cloud 导入主题）。
在主题详情页面中，点击修改。
选择启用平台日志。
点击更新。

gcloud

在 Google Cloud 控制台中，激活 Cloud Shell。

激活 Cloud Shell

Cloud Shell 会话随即会在 Google Cloud 控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。
如需启用平台日志，请确保将“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 控制台中，前往主题页面。

转到“主题”
点击您使用的相应导入主题（Cloud Storage 导入主题、Azure Event Hubs 导入主题、Amazon MSK 导入主题或 Confluent Cloud 导入主题）。
在主题详情页面中，点击修改。
取消选中启用平台日志。
点击更新。

gcloud

在 Google Cloud 控制台中，激活 Cloud Shell。

激活 Cloud Shell

Cloud Shell 会话随即会在 Google Cloud 控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。
如需停用平台日志，请确保将“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。

转到日志浏览器
选择一个 Google Cloud 项目。
如果需要，请在升级菜单中，从旧版日志查看器切换到Logs Explorer。
点击显示查询切换开关。
如需过滤日志以仅显示您正在使用的相应导入主题（Cloud Storage 导入主题、Azure Event Hubs 导入主题、Amazon MSK 导入主题或 Confluent Cloud 导入主题）的条目，请在查询字段中输入 "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": "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 或其关联公司在美国和/或其他国家/地区的注册商标。

使用平台日志排查导入主题方面的问题 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

平台日志简介

准备工作

所需的角色和权限

关于导入主题注入失败

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

文本失败

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