Usar los registros de la plataforma para solucionar problemas de importación de temas

En esta guía se explica cómo usar los registros de la plataforma para solucionar problemas al usar temas de importación, incluidos los siguientes: temas de importación de Cloud Storage, temas de importación de Azure Event Hubs, temas de importación de Amazon MSK y temas de importación de Confluent Cloud. Google Cloud

Acerca de los registros de la plataforma

Un servicio compatible Google Cloud genera su propio conjunto de registros de plataforma, que recogen eventos y actividades relevantes para el funcionamiento de ese servicio. Estos registros de la plataforma contienen información detallada sobre lo que ocurre en un servicio, incluidas las operaciones correctas, los errores, las advertencias y otros eventos importantes.

Los registros de plataforma forman parte de Cloud Logging y comparten las mismas funciones. Por ejemplo, a continuación se muestra una lista de funciones importantes de los registros de plataforma:

Para obtener más información sobre los registros de la plataforma, consulta los registros de Google Cloud Platform.

Antes de empezar

Asegúrate de que has completado los requisitos previos para crear el tema que vas a usar:

Roles y permisos necesarios

Antes de empezar, comprueba que tienes acceso a Logging. Necesitas el rol Lector de registros (roles/logging.viewer) Gestión de Identidades y Accesos (IAM). Para obtener más información sobre el acceso a Logging, consulta Control de acceso con IAM.

A continuación, se describe cómo verificar y conceder acceso de gestión de identidades y accesos:

Acerca de los errores de ingestión de temas de importación

Los temas de importación pueden tener problemas que impidan que los datos se ingieran correctamente.

Temas sobre la importación de Cloud Storage

Los temas de importación de Cloud Storage pueden tener problemas que impidan que los datos se ingieran correctamente. Por ejemplo, al usar un tema de importación de Cloud Storage, es posible que tengas problemas para ingerir un objeto de Cloud Storage o parte de un objeto.

En la siguiente lista se describen los motivos por los que se produce un fallo en la ingestión en los temas de importación de Cloud Storage que generan registros de la plataforma:

  • Tamaño del mensaje

    • Los mensajes individuales no pueden superar los 10 MB. Si lo son, se omite todo el mensaje.

    • Si usas el formato Avro o Pub/Sub Avro, los bloques Avro no pueden superar los 16 MB. Se omiten los bloques Avro más grandes.

  • Atributos del mensaje

    • Los mensajes pueden tener un máximo de 100 atributos. Los atributos adicionales se descartan cuando se ingiere el mensaje.

    • Las claves de atributo no pueden tener más de 256 bytes y los valores no pueden tener más de 1024 bytes. Si el valor es mayor que el tamaño máximo, el par clave-valor completo se elimina del mensaje cuando se ingiere.

      Para obtener más información sobre las directrices para usar claves de mensaje y atributos, consulta el artículo Usar atributos para publicar un mensaje.

  • Formato Avro

    • Asegúrate de que los objetos Avro tengan el formato correcto. El formato incorrecto impide que se ingiera el mensaje.

  • Formato de datos

Temas de importación de Azure Event Hubs, Amazon MSK y Confluent Cloud

Pueden surgir problemas al importar temas de Azure Event Hubs, Amazon MSK y Confluent Cloud que impidan que los datos se ingieran correctamente.

En la siguiente lista se describen los motivos por los que se produce un fallo en la ingestión de temas de importación que generan registros de la plataforma:

  • Tamaño del mensaje

    • Los mensajes individuales no pueden superar los 10 MB. Si lo son, se omite todo el mensaje.

  • Atributos del mensaje

    • Los mensajes pueden tener un máximo de 100 atributos. Los atributos adicionales se descartan cuando se ingiere el mensaje.

    • Las claves de atributo no pueden tener más de 256 bytes y los valores no pueden tener más de 1024 bytes. Si el valor es mayor que el tamaño máximo, el par clave-valor completo se elimina del mensaje cuando se ingiere.

      Para obtener más información sobre las directrices para usar claves de mensaje y atributos, consulta el artículo Usar atributos para publicar un mensaje.

Habilitar los registros de la plataforma

Los registros de la plataforma están inhabilitados de forma predeterminada en los temas de importación. Puede habilitar los registros de plataforma al crear o actualizar un tema de importación. Para inhabilitar los registros de la plataforma, actualiza el tema de importación.

Habilitar los registros de la plataforma al crear un tema de importación

Para habilitar los registros de la plataforma al crear un tema de importación, sigue estos pasos:

Consola

  1. En la Google Cloud consola, ve a la página Temas.

    Ir a Temas

  2. Haz clic en Crear tema.

    Se abrirá la página de detalles del tema.

  3. En el campo ID de tema, introduce un ID para el tema de importación.

    Para obtener más información sobre cómo asignar nombres a los temas, consulta las directrices de nomenclatura.

  4. Selecciona Añadir una suscripción predeterminada.

  5. Selecciona Habilitar la ingesta.

  6. Mantén el resto de los ajustes predeterminados.
  7. Haz clic en Crear tema.

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. Para habilitar los registros de la plataforma, asegúrate de que la marca --ingestion-log-severity esté definida como WARNING o un nivel de gravedad inferior, como INFO o DEBUG. Ejecuta el comando gcloud pubsub topics create para el tema correspondiente que estés usando:

    Por ejemplo, para habilitar los registros de la plataforma en un tema de importación de Cloud Storage, incluye la marca --ingestion-log-severity=WARNING en tu comando 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

Habilitar los registros de la plataforma al actualizar un tema de importación

Para habilitar los registros de la plataforma al actualizar un tema de importación, sigue estos pasos:

Consola

  1. En la Google Cloud consola, ve a la página Temas.

    Ir a Temas

  2. Haga clic en el tema de importación que esté usando (tema de importación de Cloud Storage, tema de importación de Azure Event Hubs, tema de importación de Amazon MSK o tema de importación de Confluent Cloud).

  3. En la página de detalles del tema, haz clic en Editar.

  4. Selecciona Habilitar registros de la plataforma.

  5. Haz clic en Actualizar.

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. Para habilitar los registros de la plataforma, asegúrate de que la gravedad de los registros de ingestión se haya definido como WARNING o un nivel de gravedad inferior, como INFO o DEBUG. Ejecuta el comando gcloud pubsub topics update con todas las marcas posibles que especifican la configuración del tema correspondiente que estés usando:

    Por ejemplo, para actualizar los registros de un tema de importación de Cloud Storage, incluye la marca --ingestion-log-severity=WARNING en tu comando gcloud pubsub topics create e incluye todos los valores de marca posibles que especifiquen la configuración de un tema de importación de 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

Inhabilitar registros de la plataforma

Para inhabilitar los registros de la plataforma del tema de importación que estés usando, haz lo siguiente:

Consola

  1. En la Google Cloud consola, ve a la página Temas.

    Ir a Temas

  2. Haga clic en el tema de importación que esté usando (tema de importación de Cloud Storage, tema de importación de Azure Event Hubs, tema de importación de Amazon MSK o tema de importación de Confluent Cloud).

  3. En la página de detalles del tema, haz clic en Editar.

  4. Desmarca Habilitar registros de la plataforma.

  5. Haz clic en Actualizar.

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. Para inhabilitar los registros de la plataforma, asegúrate de que la gravedad del registro de ingestión esté definida como DISABLED. Ejecuta el comando gcloud pubsub topics update con todas las marcas posibles que especifican la configuración del tema correspondiente que estés usando:

    Por ejemplo, para inhabilitar los registros en un tema de importación de Cloud Storage, incluye la marca --ingestion-log-severity=DISABLED en el comando gcloud pubsub topics update e incluye todas las marcas posibles que especifican la configuración de un tema de importación de 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

Ver registros de la plataforma

Para ver los registros de la plataforma del tema de importación que estés usando, haz lo siguiente:

Google Cloud consola

  1. En la Google Cloud consola, ve a Explorador de registros.

    Ir a Explorador de registros

  2. Selecciona un Google Cloud proyecto.

  3. Si es necesario, en el menú Actualizar, cambia de Visualizador de registros antiguo a Explorador de registros.

  4. Haz clic en el interruptor Mostrar consulta.

  5. Para filtrar los registros y mostrar solo las entradas de los temas de importación que estés usando (tema de importación de Cloud Storage, tema de importación de Azure Event Hubs, tema de importación de Amazon MSK o tema de importación de Confluent Cloud), escribe "resource.type=pubsub_topic AND severity=WARNING" en el campo de consulta y haz clic en Ejecutar consulta.

  6. En el panel Resultados de la consulta, haga clic en Editar hora para cambiar el periodo del que quiere obtener resultados.

Para obtener más información sobre cómo usar el Explorador de registros, consulta el artículo Usar el Explorador de registros.

CLI de gcloud

Para usar gcloud CLI y buscar registros de la plataforma de los temas de importación que estés usando, usa el comando gcloud logging read.

Especifica un filtro para limitar los resultados a los registros de la plataforma de los temas de importación que estés usando (tema de importación de Cloud Storage, tema de importación de Azure Event Hubs, tema de importación de Amazon MSK o tema de importación de Confluent Cloud).

gcloud logging read "resource.type=pubsub_topic AND severity=WARNING"

API de registro en la nube

Usa el método de la API entries.list Cloud Logging.

Para filtrar los resultados de forma que solo se incluyan los registros de plataforma de los temas de importación de Cloud Storage, usa el campo filter. A continuación, se muestra un objeto de solicitud JSON de ejemplo.

{
"resourceNames":
  [
    "projects/my-project-name"
  ],
  "orderBy": "timestamp desc",
  "filter": "resource.type=\"pubsub_topic\" AND severity=WARNING"
}

Ver y comprender el formato de los registros de la plataforma

En la siguiente sección se incluyen registros de plataforma de ejemplo y se describen los campos de los registros de plataforma.

Todos los campos específicos de los registros de la plataforma se incluyen en un objeto jsonPayload.

Cloud Storage

Error de 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"
}
Campo de registro Descripción
insertId Identificador único de la entrada de registro.
jsonPayload.@type Identifica el tipo de evento. Siempre type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.cloudStorageFailure.objectGeneration Número de generación del objeto de Cloud Storage.
jsonPayload.cloudStorageFailure.bucket El segmento de Cloud Storage que contiene el objeto.
jsonPayload.cloudStorageFailure.objectName Nombre del objeto de Cloud Storage.
jsonPayload.cloudStorageFailure.avroFailureReason Contiene detalles más específicos sobre el error de análisis de Avro. Este campo se deja vacío.
jsonPayload.topic El tema de Pub/Sub al que se ha enviado el mensaje.
jsonPayload.errorMessage Mensaje de error legible por humanos.
resource.type El tipo de recurso. Siempre pubsub_topic.
resource.labels.project_id El Google Cloud ID del proyecto.
resource.labels.topic_id ID del tema de Pub/Sub.
timestamp Marca de tiempo de generación de la entrada de registro.
severity Nivel de gravedad WARNING.
logName Nombre del registro.
receiveTimestamp Marca de tiempo de recepción de la entrada de registro.

Fallo de texto 

{
  "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"
}
Campo de registro Descripción
insertId Identificador único de la entrada de registro.
jsonPayload.@type Identifica el tipo de evento. Siempre type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.cloudStorageFailure.objectGeneration Número de generación del objeto de Cloud Storage.
jsonPayload.cloudStorageFailure.bucket El segmento de Cloud Storage que contiene el objeto.
jsonPayload.cloudStorageFailure.objectName Nombre del objeto de Cloud Storage.
jsonPayload.cloudStorageFailure.apiViolationReason Contiene detalles sobre la infracción de la API. Este campo se deja vacío.
jsonPayload.topic El tema de Pub/Sub.
jsonPayload.errorMessage Mensaje legible por humanos.
resource.type Tipo de recurso, siempre pubsub_topic.
resource.labels.project_id Google Cloud ID de proyecto.
resource.labels.topic_id ID del tema de Pub/Sub.
timestamp Marca de tiempo de generación de la entrada de registro.
severity Nivel de gravedad WARNING.
logName Nombre del registro.
receiveTimestamp Hora a la que Cloud Logging recibió la entrada de registro.

Amazon MSK

Infracción de la 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"
}
Campo de registro Descripción
insertId Identificador único de la entrada de registro.
jsonPayload.@type Identifica el tipo de evento. Siempre type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.awsMskFailure.clusterArn ARN del clúster del tema del que se está ingiriendo.
jsonPayload.awsMskFailure.kafkaTopic El nombre del tema de Kafka del que se ingieren datos.
jsonPayload.awsMskFailure.partitionId ID de la partición que contiene el mensaje que no se ha podido ingerir.
jsonPayload.awsMskFailure.offset El desplazamiento dentro de la partición del mensaje que no se ha podido ingerir.
jsonPayload.awsMskFailure.apiViolationReason Contiene detalles sobre la infracción de la API. Este campo se deja vacío.
jsonPayload.topic El tema de Pub/Sub.
jsonPayload.errorMessage Mensaje legible por humanos.
resource.type Tipo de recurso, siempre pubsub_topic.
resource.labels.project_id Google Cloud ID de proyecto.
resource.labels.topic_id ID del tema de Pub/Sub.
timestamp Marca de tiempo de generación de la entrada de registro.
severity Nivel de gravedad WARNING.
logName Nombre del registro.
receiveTimestamp Hora a la que Cloud Logging recibió la entrada de registro.

Azure Event Hubs

Infracción de la 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"
}
Campo de registro Descripción
insertId Identificador único de la entrada de registro.
jsonPayload.@type Identifica el tipo de evento. Siempre type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.azureEventHubsFailure.namespace El espacio de nombres que contiene el centro de eventos del que se ingieren datos.
jsonPayload.azureEventHubsFailure.eventHub Nombre del centro de eventos del que se ingieren datos.
jsonPayload.azureEventHubsFailure.partitionId ID de la partición que contiene el mensaje que no se ha podido ingerir.
jsonPayload.azureEventHubsFailure.offset El desplazamiento dentro de la partición del mensaje que no se ha podido ingerir.
jsonPayload.azureEventHubsFailure.apiViolationReason Contiene detalles sobre la infracción de la API. Este campo se deja vacío.
jsonPayload.topic El tema de Pub/Sub.
jsonPayload.errorMessage Mensaje legible por humanos.
resource.type Tipo de recurso, siempre pubsub_topic.
resource.labels.project_id Google Cloud ID de proyecto.
resource.labels.topic_id ID del tema de Pub/Sub.
timestamp Marca de tiempo de generación de la entrada de registro.
severity Nivel de gravedad WARNING.
logName Nombre del registro.
receiveTimestamp Hora a la que Cloud Logging recibió la entrada de registro.

Confluent Cloud

Fallo de texto 

{
  "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"
}
Campo de registro Descripción
insertId Identificador único de la entrada de registro.
jsonPayload.@type Identifica el tipo de evento. Siempre type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.confluentCloudFailure.clusterId El ID del clúster que contiene el tema del que se ingiere.
jsonPayload.confluentCloudFailure.kafkaTopic El nombre del tema de Kafka del que se ingieren datos.
jsonPayload.confluentCloudFailure.partitionId ID de la partición que contiene el mensaje que no se ha podido ingerir.
jsonPayload.confluentCloudFailure.offset El desplazamiento dentro de la partición del mensaje que no se ha podido ingerir.
jsonPayload.confluentCloudFailure.apiViolationReason Contiene detalles sobre la infracción de la API. Este campo se deja vacío.
jsonPayload.topic El tema de Pub/Sub.
jsonPayload.errorMessage Mensaje legible por humanos.
resource.type Tipo de recurso, siempre pubsub_topic.
resource.labels.project_id ID del proyecto de Google Cloud.
resource.labels.topic_id ID del tema de Pub/Sub.
timestamp Marca de tiempo de generación de la entrada de registro.
severity Nivel de gravedad WARNING.
logName Nombre del registro.
receiveTimestamp Hora a la que Cloud Logging recibió la entrada de registro.
Apache Kafka® es una marca registrada de Apache Software Foundation o sus filiales en Estados Unidos u otros países.