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

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

平台日志简介

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

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

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

准备工作

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

所需的角色和权限

在开始之前，请验证您是否有权访问 Logging。 您需要拥有 日志查看器 (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. 在 Cloud de Confiance 控制台中，前往主题页面。

    转到“主题”

  2. 点击创建主题。

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

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

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

  4. 选择添加默认订阅。

  5. 选择启用注入。

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

gcloud

  1. 在 Cloud de Confiance 控制台中，激活 Cloud Shell。

    激活 Cloud Shell

    Cloud Shell 会话随即会在 Cloud de Confiance 控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。

  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. 在 Cloud de Confiance 控制台中，前往主题页面。

    转到“主题”

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

  3. 在主题详情页面中，点击修改。

  4. 选择启用平台日志。

  5. 点击更新。

gcloud

  1. 在 Cloud de Confiance 控制台中，激活 Cloud Shell。

    激活 Cloud Shell

    Cloud Shell 会话随即会在 Cloud de Confiance 控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。

  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. 在 Cloud de Confiance 控制台中，前往主题页面。

    转到“主题”

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

  3. 在主题详情页面中，点击修改。

  4. 清除启用平台日志。

  5. 点击更新。

gcloud

  1. 在 Cloud de Confiance 控制台中，激活 Cloud Shell。

    激活 Cloud Shell

    Cloud Shell 会话随即会在 Cloud de Confiance 控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。

  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

查看平台日志

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

Cloud de Confiance 控制台

  1. 在 Cloud de Confiance 控制台中，前往 Logs Explorer。

    转到日志浏览器

  2. 选择一个 Cloud de Confiance 项目。

  3. 如有需要，在升级菜单中，从旧版日志查看器切换到Logs Explorer。

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

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

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

如需详细了解如何使用 Logs Explorer，请参阅使用 Logs Explorer。

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 Cloud de Confiance 项目 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 Cloud de Confiance 项目 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 Cloud de Confiance 项目 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 Cloud de Confiance 项目 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 或其关联公司在美国和/或其他国家/地区的注册商标。