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

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

平台日志简介

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

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

如需详细了解平台日志，请参阅 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 对象格式正确。格式不正确会导致消息无法被提取。

  • 数据格式

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. 如需停用平台日志，请确保将“ingestion-log-severity”设置为 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. 如果需要，请在升级菜单中，从旧版日志查看器切换到日志浏览器。

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