Usa los registros de la plataforma para solucionar problemas de importación

En esta guía, se explica cómo usar los Google Cloud registros de la plataforma para solucionar problemas cuando usas 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.

Información acerca de los registros de la plataforma

Un servicio Google Cloud compatible genera su propio conjunto de registros de la plataforma, que capturan eventos y actividades relevantes para el funcionamiento de ese servicio. Estos registros de la plataforma contienen información detallada sobre lo que sucede dentro de 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, la siguiente es una lista de funciones importantes para los registros de la plataforma:

  • Por lo general, los registros están estructurados como objetos JSON que permiten realizar más consultas y filtraciones.

  • Puedes ver los registros de la plataforma con la función para acceder a la consola.

  • Los registros de la plataforma también se pueden integrar con Cloud Monitoring y otras herramientas de supervisión para crear paneles, alertas y otros mecanismos de supervisión.

  • El almacenamiento de registros genera costos en función del volumen transferido y el período de retención.

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

Antes de comenzar

Asegúrate de haber completado los requisitos previos para crear el tema que estás usando:

Roles y permisos requeridos

Antes de comenzar, verifica que tengas acceso a Logging. Necesitas el rol de administración de identidades y accesos (IAM) (roles/logging.viewer) de Visualizador de registros. Para obtener más información sobre el acceso de Logging, consulta Control de acceso con IAM.

A continuación, se describe cómo verificar y otorgar el acceso a IAM:

Acerca de las fallas de transferencia de temas de importación

Los temas de importación pueden tener problemas que impiden que los datos se transfieran correctamente.

Temas de importación de Cloud Storage

Los temas de importación de Cloud Storage pueden tener problemas que impidan que los datos se transfieran correctamente. Por ejemplo, cuando usas un tema de importación de Cloud Storage, es posible que tengas problemas para transferir un objeto de Cloud Storage o parte de un objeto.

En la siguiente lista, se describen los motivos de los errores de transferencia en los temas de importación de Cloud Storage que generan registros de la plataforma:

  • Tamaño del mensaje

    • Los mensajes individuales no pueden tener un tamaño superior a 10 MB. Si es así, se omite todo el mensaje.

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

  • Atributos del mensaje

    • Los mensajes pueden tener un máximo de 100 atributos. Cualquier atributo adicional se descarta cuando se transfiere el mensaje.

    • Las claves de atributo no pueden ser mayores a 256 bytes, y los valores no pueden ser mayores a 1,024 bytes. Si el valor es mayor que el tamaño máximo, se descarta todo el par clave-valor del mensaje cuando se transfiere.

      Para obtener más información sobre los lineamientos para usar claves y atributos de mensajes, consulta Cómo usar atributos para publicar un mensaje.

  • Formato Avro

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

  • Formato de los datos

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

Los temas de importación de Azure Event Hubs, Amazon MSK y Confluent Cloud pueden encontrar problemas que impiden que los datos se transfieran correctamente.

En la siguiente lista, se describen los motivos de las fallas de transferencia en los temas de importación que generan registros de la plataforma:

  • Tamaño del mensaje

    • Los mensajes individuales no pueden tener un tamaño superior a 10 MB. Si es así, se omite todo el mensaje.

  • Atributos del mensaje

    • Los mensajes pueden tener un máximo de 100 atributos. Cualquier atributo adicional se descarta cuando se transfiere el mensaje.

    • Las claves de atributos no pueden ser mayores a 256 bytes, y los valores no pueden ser mayores a 1,024 bytes. Si el valor es mayor que el tamaño máximo, se descarta todo el par clave-valor del mensaje cuando se transfiere.

      Para obtener más información sobre los lineamientos para usar claves y atributos de mensajes, consulta Cómo usar atributos para publicar un mensaje.

Habilita los registros de la plataforma

Los registros de la plataforma están inhabilitados de forma predeterminada para los temas de importación. Puedes habilitar los registros de la plataforma cuando creas o actualizas un tema de importación. Para inhabilitar los registros de la plataforma, actualiza el tema de importación.

Habilita los registros de la plataforma cuando crees un tema de importación

Para habilitar los registros de la plataforma cuando creas un tema de importación, haz lo siguiente:

Console

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

    Ir a temas

  2. Haz clic en Crear un tema.

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

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

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

  4. Selecciona Agregar una suscripción predeterminada.

  5. Selecciona Habilitar transferencia.

  6. Mantén la configuración predeterminada.
  7. Haz clic en Crear un 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é establecida en WARNING o en un nivel de gravedad inferior, como INFO o DEBUG. Ejecuta el comando gcloud pubsub topics create para el tema que usas:

    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 el 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

Habilita los registros de la plataforma mientras actualizas un tema de importación

Para habilitar los registros de la plataforma cuando se actualiza un tema de importación, haz lo siguiente:

Console

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

    Ir a temas

  2. Haz clic en el tema de importación que usas (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 ingestion-log-severity esté configurado en WARNING o en un nivel de gravedad inferior, como INFO o DEBUG. Ejecuta el comando gcloud pubsub topics update con todas las marcas posibles que especifiquen la configuración del tema que estás usando:

    Por ejemplo, para actualizar los registros de un tema de importación de Cloud Storage existente, incluye la marca --ingestion-log-severity=WARNING en el comando gcloud pubsub topics create y 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

Inhabilita los registros de la plataforma

Para inhabilitar los registros de la plataforma para el tema de importación que usas, haz lo siguiente:

Console

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

    Ir a temas

  2. Haz clic en el tema de importación que usas (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. Borra Habilitar los 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 ingestion-log-severity esté configurado en DISABLED. Ejecuta el comando gcloud pubsub topics update con todas las marcas posibles que especifiquen la configuración del tema que estás usando:

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

Cómo ver los registros de la plataforma

Para ver los registros de la plataforma del tema de importación que usas, haz lo siguiente:

Consola de Google Cloud

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

    Ir al Explorador de registros

  2. Selecciona un proyecto de Google Cloud.

  3. Si es necesario, en el menú Actualizar, cambia del Visor de registros heredados a Explorador de registros.

  4. Haz clic en el botón de activar o desactivar Mostrar consulta.

  5. Para filtrar tus registros de modo que solo muestren las entradas de los temas de importación que usas (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="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, haz clic en Editar hora para cambiar el período de los resultados mostrados.

Para obtener más información sobre el uso del Explorador de registros, consulta Usa el Explorador de registros.

gcloud CLI

Para usar la CLI de gcloud a fin de buscar registros de la plataforma para los temas de importación que usas, usa el comando gcloud logging read.

Especifica un filtro para limitar tus resultados a los registros de la plataforma de los temas de importación que usas (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 Cloud Logging

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

Para filtrar tus resultados y que solo incluyan registros de la plataforma para los temas de importación de Cloud Storage, usa el campo filter. El siguiente es un objeto de solicitud JSON de muestra.

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

Cómo ver y comprender el formato de registro de la plataforma

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

Todos los campos específicos del registro de la plataforma se encuentran dentro de un objeto jsonPayload.

Cloud Storage

Falla 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 Indica un identificador único para la entrada de registro.
jsonPayload.@type Identifica el tipo de evento. Siempre type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.cloudStorageFailure.objectGeneration El número de generación del objeto de Cloud Storage.
jsonPayload.cloudStorageFailure.bucket El bucket de Cloud Storage que contiene el objeto
jsonPayload.cloudStorageFailure.objectName El nombre del objeto de Cloud Storage.
jsonPayload.cloudStorageFailure.avroFailureReason Contiene detalles más específicos del error de análisis de Avro. Este campo se deja vacío.
jsonPayload.topic El tema de Pub/Sub para el que estaba destinado el mensaje.
jsonPayload.errorMessage Un mensaje de error legible por humanos.
resource.type El tipo del recurso. Siempre pubsub_topic.
resource.labels.project_id El Google Cloud ID del proyecto.
resource.labels.topic_id El ID del tema de Pub/Sub.
timestamp Marca de tiempo de generación de la entrada del registro.
severity Nivel de gravedad, que es WARNING.
logName Nombre del registro.
receiveTimestamp Marca de tiempo de recepción de la entrada de registro.

Error 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 Indica un identificador único para la entrada de registro.
jsonPayload.@type Identifica el tipo de evento. Siempre type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.cloudStorageFailure.objectGeneration El número de generación del objeto de Cloud Storage.
jsonPayload.cloudStorageFailure.bucket El bucket de Cloud Storage que contiene el objeto
jsonPayload.cloudStorageFailure.objectName El nombre del objeto de Cloud Storage.
jsonPayload.cloudStorageFailure.apiViolationReason Contiene detalles sobre el incumplimiento de la API. Este campo se deja vacío.
jsonPayload.topic El tema de Pub/Sub.
jsonPayload.errorMessage Un mensaje legible por humanos.
resource.type Tipo de recurso, siempre pubsub_topic.
resource.labels.project_id ID del proyecto deGoogle Cloud .
resource.labels.topic_id ID del tema de Pub/Sub.
timestamp Marca de tiempo de generación de la entrada del registro.
severity Nivel de gravedad, que es WARNING.
logName Nombre del registro.
receiveTimestamp Hora en la que Cloud Logging recibió la entrada de registro.

Amazon MSK

Incumplimiento 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 Indica un identificador único para la entrada de registro.
jsonPayload.@type Identifica el tipo de evento. Siempre type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.awsMskFailure.clusterArn El ARN del clúster del tema del que se transfiere el contenido.
jsonPayload.awsMskFailure.kafkaTopic Es el nombre del tema de Kafka desde el que se transfiere la información.
jsonPayload.awsMskFailure.partitionId El ID de la partición que contiene el mensaje que no se pudo transferir.
jsonPayload.awsMskFailure.offset Es el desplazamiento dentro de la partición del mensaje que no se pudo transferir.
jsonPayload.awsMskFailure.apiViolationReason Contiene detalles sobre el incumplimiento de la API. Este campo se deja vacío.
jsonPayload.topic El tema de Pub/Sub.
jsonPayload.errorMessage Un mensaje legible por humanos.
resource.type Tipo de recurso, siempre pubsub_topic.
resource.labels.project_id ID del proyecto deGoogle Cloud .
resource.labels.topic_id ID del tema de Pub/Sub.
timestamp Marca de tiempo de generación de la entrada del registro.
severity Nivel de gravedad, que es WARNING.
logName Nombre del registro.
receiveTimestamp Hora en la que Cloud Logging recibió la entrada de registro.

Azure Event Hubs

Incumplimiento 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 Indica un identificador único para 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 desde el que se transfiere la información
jsonPayload.azureEventHubsFailure.eventHub Es el nombre del centro de eventos desde el que se transfiere la información.
jsonPayload.azureEventHubsFailure.partitionId El ID de la partición que contiene el mensaje que no se pudo transferir.
jsonPayload.azureEventHubsFailure.offset Es el desplazamiento dentro de la partición del mensaje que no se pudo transferir.
jsonPayload.azureEventHubsFailure.apiViolationReason Contiene detalles sobre el incumplimiento de la API. Este campo se deja vacío.
jsonPayload.topic El tema de Pub/Sub.
jsonPayload.errorMessage Un mensaje legible por humanos.
resource.type Tipo de recurso, siempre pubsub_topic.
resource.labels.project_id ID del proyecto deGoogle Cloud .
resource.labels.topic_id ID del tema de Pub/Sub.
timestamp Marca de tiempo de generación de la entrada del registro.
severity Nivel de gravedad, que es WARNING.
logName Nombre del registro.
receiveTimestamp Hora en la que Cloud Logging recibió la entrada de registro.

Confluent Cloud

Error 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 Indica un identificador único para 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 transfiere el contenido.
jsonPayload.confluentCloudFailure.kafkaTopic Es el nombre del tema de Kafka desde el que se transfiere la información.
jsonPayload.confluentCloudFailure.partitionId El ID de la partición que contiene el mensaje que no se pudo transferir.
jsonPayload.confluentCloudFailure.offset Es el desplazamiento dentro de la partición del mensaje que no se pudo transferir.
jsonPayload.confluentCloudFailure.apiViolationReason Contiene detalles sobre el incumplimiento de la API. Este campo se deja vacío.
jsonPayload.topic El tema de Pub/Sub.
jsonPayload.errorMessage Un 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 del registro.
severity Nivel de gravedad, que es WARNING.
logName Nombre del registro.
receiveTimestamp Hora en la que Cloud Logging recibió la entrada de registro.
Apache Kafka® es una marca registrada de The Apache Software Foundation o sus afiliados de Estados Unidos y otros países.