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

控制台

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

   转到“主题”

2. 点击创建主题。

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

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

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

4. 选择添加默认订阅。

5. 选择启用提取。

6. 按照创建 Cloud Storage 导入主题中的说明指定提取选项。
7. 选择启用平台日志。
8. 保留其他默认设置。
9. 点击创建主题。

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 或更高级别。运行 gcloud pubsub topics create 命令：

   gcloud pubsub topics create TOPIC_ID\
       --cloud-storage-ingestion-bucket=BUCKET_NAME\
       --cloud-storage-ingestion-input-format=INPUT_FORMAT\
       --ingestion-log-severity=WARNING

   替换以下内容：

   • TOPIC_ID：主题的名称或 ID。

   • BUCKET_NAME：指定现有存储桶的名称。例如 prod_bucket。 存储桶名称不得包含项目 ID。如需创建存储桶，请参阅创建存储桶。

   • INPUT_FORMAT：指定要提取的对象的格式。可以是 text、avro 或 pubsub_avro。如需详细了解这些选项，请参阅输入格式。

控制台

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

   转到“主题”

2. 点击“Cloud Storage 导入”主题。

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. 为避免丢失导入主题的设置，请务必在每次更新主题时添加所有设置。如果您遗漏了某些内容，Pub/Sub 会将设置重置为原始默认值。

   如需启用平台日志，请确保 ingestion-log-severity 设置为 WARNING。使用以下示例中提及的所有标志运行 gcloud pubsub topics update 命令：

   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

   替换以下内容：

   • TOPIC_ID 是主题 ID 或名称。此字段无法更新。

   • BUCKET_NAME：指定现有存储桶的名称。例如 prod_bucket。 存储桶名称不得包含项目 ID。

   • INPUT_FORMAT：指定要提取的对象的格式。可以是 text、avro 或 pubsub_avro。如需详细了解这些选项，请参阅输入格式。

   • TEXT_DELIMITER：指定用于将文本对象拆分为 Pub/Sub 消息的分隔符。此字符应为单个字符，并且仅应在 INPUT_FORMAT 为 text 时设置。默认值为换行符 (\n)。

     使用 gcloud CLI 指定分隔符时，请仔细注意对新行 \n 等特殊字符的处理。使用 '\n' 格式确保正确解读分隔符。仅使用 \n（不带引号或转义）会导致分隔符为 "n"。

   • MINIMUM_OBJECT_CREATE_TIME：指定对象的创建时间不得低于此值，才能被提取。此值应采用 UTC 格式，格式为 YYYY-MM-DDThh:mm:ssZ。例如 2024-10-14T08:30:30Z。

     从 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59Z（包括这两个数值）之间的任何日期（过去或未来）均有效。

   • MATCH_GLOB：指定要匹配的 glob 模式，以便提取对象。使用 gcloud CLI 时，包含 * 字符的匹配正则表达式必须将 * 字符的格式设置为转义形式（\*\*.txt），或者整个匹配正则表达式必须用引号 "**.txt" 或 '**.txt' 括起来。如需了解 glob 模式支持的语法，请参阅 Cloud Storage 文档。

控制台

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

   转到“主题”

2. 点击“Cloud Storage 导入”主题。

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. 为避免丢失导入主题的设置，请务必在每次更新主题时添加所有设置。如果您遗漏了某些内容，Pub/Sub 会将设置重置为原始默认值。

   如需停用平台日志，请确保将 ingestion-log-severity 设置为 DISABLED。使用以下示例中提及的所有标志运行 gcloud pubsub topics update 命令：

   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

   替换以下内容：

   • TOPIC_ID 是主题 ID 或名称。此字段无法更新。

   • BUCKET_NAME：指定现有存储桶的名称。例如 prod_bucket。 存储桶名称不得包含项目 ID。

   • INPUT_FORMAT：指定要提取的对象的格式。可以是 text、avro 或 pubsub_avro。如需详细了解这些选项，请参阅输入格式。

   • TEXT_DELIMITER：指定用于将文本对象拆分为 Pub/Sub 消息的分隔符。此字符应为单个字符，并且仅应在 INPUT_FORMAT 为 text 时设置。默认值为换行符 (\n)。

     使用 gcloud CLI 指定分隔符时，请仔细注意对新行 \n 等特殊字符的处理。使用 '\n' 格式确保正确解读分隔符。仅使用 \n（不带引号或转义）会导致分隔符为 "n"。

   • MINIMUM_OBJECT_CREATE_TIME：指定对象的创建时间不得低于此值，才能被提取。此值应采用 UTC 格式，格式为 YYYY-MM-DDThh:mm:ssZ。例如 2024-10-14T08:30:30Z。

     从 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59Z（包括这两个数值）之间的任何日期（过去或未来）均有效。

   • MATCH_GLOB：指定要匹配的 glob 模式，以便提取对象。使用 gcloud CLI 时，包含 * 字符的匹配正则表达式必须将 * 字符的格式设置为转义形式（\*\*.txt），或者整个匹配正则表达式必须用引号 "**.txt" 或 '**.txt' 括起来。如需了解 glob 模式支持的语法，请参阅 Cloud Storage 文档。

Google Cloud 控制台

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

   转到日志浏览器

2. 选择 Google Cloud 项目。

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

4. 如需过滤日志以仅显示 Cloud Storage 导入主题的条目，请在查询字段中输入 resource.type="resource.type=pubsub_topic AND severity=WARNING，然后点击运行查询。

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

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

gcloud CLI

如需使用 gcloud CLI 搜索 Cloud Storage 导入主题的平台日志，请使用 gcloud logging read 命令。

指定过滤条件以将结果限制为 Cloud Storage 导入主题的平台日志。

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"
}

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/interpod-p2-management/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": "interpod-p2-management",
      "topic_id": "avro_bucket_topic"
    }
  },
  "timestamp": "2024-10-07T18:55:45.650103193Z",
  "severity": "WARNING",
  "logName": "projects/interpod-p2-management/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-07T18:55:46.678221398Z"
}

文本失败

{
  "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/interpod-p2-management/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": "interpod-p2-management"
    }
  },
  "timestamp": "2024-10-09T14:09:07.760488386Z",
  "severity": "WARNING",
  "logName": "projects/interpod-p2-management/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-09T14:09:08.483589656Z"
}