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

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

Acerca de los registros de plataforma

Un servicio Google Cloud compatible genera su propio conjunto de registros de la plataforma, en los que se capturan los eventos y las actividades pertinentes 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 exitosas, 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 para los registros de la plataforma:

  • Por lo general, los registros se estructuran como objetos JSON que permiten realizar más consultas y filtrados.

  • Puedes ver los registros de la plataforma con la opción Logging in the console.

  • 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 según el 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 usas:

Roles y permisos requeridos

Antes de comenzar, verifica que tengas acceso a Logging. Necesitas el rol de Visualizador de registros de (roles/logging.viewer) Identity and Access Management (IAM). 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 en la transferencia de temas de importación

Los temas de importación pueden tener problemas que impidan 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 por los que falla la 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 superar los 10 MB. Si es así, se omite todo el mensaje.

    • Si usas el formato Avro o Pub/Sub Avro, los bloques de Avro no pueden superar los 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 procesa el mensaje.

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

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

  • Formato Avro

    • Asegúrate de que tus objetos Avro tengan el formato correcto. El formato incorrecto impide que se ingiera 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 tener problemas que impidan la transferencia correcta de datos.

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

  • Tamaño del mensaje

    • Los mensajes individuales no pueden superar los 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 procesa el mensaje.

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

      Para obtener más información sobre los lineamientos para usar claves y atributos de mensajes, consulta Usa 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 crees o actualices un tema de importación. Para inhabilitar los registros de la plataforma, actualiza el tema de importación.

Habilita los registros de la plataforma mientras creas 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 del tema, ingresa un ID para el tema de importación.

    Para obtener más información sobre cómo nombrar temas, consulta los lineamientos para asignar 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 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

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

Para habilitar los registros de la plataforma cuando actualices 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 correspondiente 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).

  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 especifican la configuración del tema respectivo que estás usando:

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

Inhabilita los registros de la plataforma

Para inhabilitar los registros de la plataforma para el tema de importación respectivo que estás usando, 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 correspondiente 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).

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

  4. Borra 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 ingestion-log-severity esté configurado como DISABLED. Ejecuta el comando gcloud pubsub topics update con todas las marcas posibles que especifican la configuración del tema respectivo 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 tu comando gcloud pubsub topics update y 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

Cómo ver los registros de la plataforma

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

Google Cloud console

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

    Ir al Explorador de registros

  2. Selecciona un Google Cloud proyecto.

  3. Si es necesario, en el menú Actualizar, cambia de 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 respectivos 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 gcloud CLI y buscar registros de la plataforma para los temas de importación respectivos que usas, usa el comando gcloud logging read.

Especifica un filtro para limitar tus resultados a los registros de la plataforma de los respectivos 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 Cloud Logging

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

Para filtrar tus resultados y que solo incluyan los registros de la plataforma para 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"
}

Cómo ver y comprender el formato de los registros 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 Es el número de generación del objeto de Cloud Storage.
jsonPayload.cloudStorageFailure.bucket Es el bucket de Cloud Storage que contiene el objeto.
jsonPayload.cloudStorageFailure.objectName Es el 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 queda vacío.
jsonPayload.topic Es el tema de Pub/Sub para el que se envió el mensaje.
jsonPayload.errorMessage Es un mensaje de error legible.
resource.type El tipo del recurso. Siempre pubsub_topic.
resource.labels.project_id ID del proyecto Google Cloud
resource.labels.topic_id Es el ID del tema de Pub/Sub.
timestamp Es la marca de tiempo de generación de la entrada de registro.
severity Es el nivel de gravedad, que es WARNING.
logName Nombre del registro.
receiveTimestamp Es la marca de tiempo de recepción de la entrada de registro.

Falla 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 Es el número de generación del objeto de Cloud Storage.
jsonPayload.cloudStorageFailure.bucket Es el bucket de Cloud Storage que contiene el objeto.
jsonPayload.cloudStorageFailure.objectName Es el nombre del objeto de Cloud Storage.
jsonPayload.cloudStorageFailure.apiViolationReason Contiene detalles sobre el incumplimiento de la API. Este campo queda vacío.
jsonPayload.topic Es el tema de Pub/Sub.
jsonPayload.errorMessage Es un mensaje legible.
resource.type Tipo de recurso, siempre pubsub_topic.
resource.labels.project_id ID del proyectoGoogle Cloud .
resource.labels.topic_id ID del tema de Pub/Sub.
timestamp Es la marca de tiempo de generación de la entrada de registro.
severity Es el nivel de gravedad, que es WARNING.
logName Nombre del registro.
receiveTimestamp Fecha y hora en 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 ARN del clúster del que se ingiere el tema.
jsonPayload.awsMskFailure.kafkaTopic Es el nombre del tema de Kafka desde el que se realiza la transferencia de datos.
jsonPayload.awsMskFailure.partitionId Es 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 queda vacío.
jsonPayload.topic Es el tema de Pub/Sub.
jsonPayload.errorMessage Es un mensaje legible.
resource.type Tipo de recurso, siempre pubsub_topic.
resource.labels.project_id ID del proyectoGoogle Cloud .
resource.labels.topic_id ID del tema de Pub/Sub.
timestamp Es la marca de tiempo de generación de la entrada de registro.
severity Es el nivel de gravedad, que es WARNING.
logName Nombre del registro.
receiveTimestamp Fecha y hora en 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 Es el espacio de nombres que contiene el centro de eventos desde el que se realiza la transferencia.
jsonPayload.azureEventHubsFailure.eventHub Es el nombre del centro de eventos desde el que se realiza la transferencia.
jsonPayload.azureEventHubsFailure.partitionId Es 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 queda vacío.
jsonPayload.topic Es el tema de Pub/Sub.
jsonPayload.errorMessage Es un mensaje legible.
resource.type Tipo de recurso, siempre pubsub_topic.
resource.labels.project_id ID del proyectoGoogle Cloud .
resource.labels.topic_id ID del tema de Pub/Sub.
timestamp Es la marca de tiempo de generación de la entrada de registro.
severity Es el nivel de gravedad, que es WARNING.
logName Nombre del registro.
receiveTimestamp Fecha y hora en que Cloud Logging recibió la entrada de registro.

Confluent Cloud

Falla 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 Es el ID del clúster que contiene el tema del que se realiza la transferencia.
jsonPayload.confluentCloudFailure.kafkaTopic Es el nombre del tema de Kafka desde el que se realiza la transferencia de datos.
jsonPayload.confluentCloudFailure.partitionId Es 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 queda vacío.
jsonPayload.topic Es el tema de Pub/Sub.
jsonPayload.errorMessage Es un mensaje legible.
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 Es la marca de tiempo de generación de la entrada de registro.
severity Es el nivel de gravedad, que es WARNING.
logName Nombre del registro.
receiveTimestamp Fecha y hora en que Cloud Logging recibió la entrada de registro.
Apache Kafka® es una marca registrada de The Apache Software Foundation o sus afiliados en Estados Unidos y otros países.