Se usó la API de Cloud Translation para traducir esta página.

Usa los registros de la plataforma para solucionar problemas relacionados con la importación de Cloud Storage

En esta guía, se explica cómo usar los registros de Google Cloud Platform para solucionar problemas cuando usas los temas de importación de Cloud Storage para transferir datos.

Acerca de los errores de transferencia en los 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 mensajes no pueden tener un tamaño superior a 16 MB. Se omiten los bloques de mensajes 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 atributos no pueden ser mayores a 256 bytes, y los valores no pueden ser mayores a 1,024 bytes. Las claves o los valores más grandes se quitan 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
- Asegúrate de usar una versión compatible de Avro. No se procesan los formatos no admitidos.

Información acerca de los registros de plataforma

Un servicio compatible de Google Cloud 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.

Roles y permisos obligatorios para usar los registros de la plataforma

Antes de comenzar, verifica que tengas acceso a Logging. Necesitas el rol de Identity and Access Management (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:

Visualiza el acceso actual para verificar el acceso que tiene cada principal.
Otorga un rol a las principales relevantes de tu proyecto.

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 de Cloud Storage.

Para inhabilitar los registros de la plataforma, actualiza el tema de importación de Cloud Storage.

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

Asegúrate de haber completado los requisitos previos para crear un tema de importación de Cloud Storage.

Para crear un tema de importación de Cloud Storage con los registros de la plataforma habilitados, sigue estos pasos:

Console

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

Ir a temas
Haz clic en Crear tema.
Se abrirá la página de detalles del tema.
En el campo ID de tema, ingresa un ID para tu tema de importación de Cloud Storage.
Para obtener más información sobre cómo asignar nombres a los temas, consulta los lineamientos de nombres.
Selecciona Agregar una suscripción predeterminada.
Selecciona Habilitar transferencia.
Para especificar las opciones de transferencia, sigue las instrucciones que se indican en Cómo crear un tema de importación de Cloud Storage.
Selecciona Habilitar registros de la plataforma.
Mantén la configuración predeterminada.
Haz clic en Crear tema.

gcloud

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.
Para habilitar los registros de la plataforma, asegúrate de que la marca --ingestion-log-severity esté configurada en WARNING o una versión posterior. Ejecuta 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
```
Reemplaza lo siguiente:
- TOPIC_ID: Es el nombre o el ID de tu tema.
- BUCKET_NAME: Especifica el nombre de un bucket existente. Por ejemplo, prod_bucket El nombre del bucket no debe incluir el ID del proyecto. Para crear un bucket, consulta Crea buckets.
- INPUT_FORMAT: Especifica el formato de los objetos que se transfieren. Puede ser text, avro o pubsub_avro. Para obtener más información sobre estas opciones, consulta Formato de entrada.

Si tienes problemas, consulta Cómo solucionar problemas relacionados con un tema de importación de Cloud Storage.

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

Sigue los siguientes pasos:

Console

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

Ir a temas
Haz clic en el tema de importación de Cloud Storage.
En la página de detalles del tema, haz clic en Editar.
Selecciona Habilitar registros de la plataforma.
Haz clic en Actualizar.

gcloud

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.
Para evitar perder la configuración del tema de importación, asegúrate de incluirlos todos cada vez que lo actualices. Si omites algo, Pub/Sub restablece la configuración a su valor predeterminado original.

Para habilitar los registros de la plataforma, asegúrate de que ingestion-log-severity esté configurado en WARNING. Ejecuta el comando gcloud pubsub topics update con todas las marcas mencionadas en el siguiente ejemplo:
```
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
```
Reemplaza lo siguiente:
- TOPIC_ID es el ID o el nombre del tema. No se puede actualizar este campo.
- BUCKET_NAME: Especifica el nombre de un bucket existente. Por ejemplo, prod_bucket El nombre del bucket no debe incluir el ID del proyecto.
- INPUT_FORMAT: Especifica el formato de los objetos que se transfieren. Puede ser text, avro o pubsub_avro. Para obtener más información sobre estas opciones, consulta Formato de entrada.
- TEXT_DELIMITER: Especifica el delimitador con el que se dividirán los objetos de texto en mensajes de Pub/Sub. Debe ser un solo carácter y solo debe establecerse cuando INPUT_FORMAT sea text. El valor predeterminado es el carácter de salto de línea (\n).
  
  Cuando uses gcloud CLI para especificar el delimitador, presta mucha atención a la manipulación de caracteres especiales, como el carácter de línea nueva \n. Usa el formato '\n' para asegurarte de que el delimitador se interprete correctamente. Simplemente, usar \n sin comillas o sin escapar los resultados genera un delimitador de "n".
- MINIMUM_OBJECT_CREATE_TIME: Especifica el tiempo mínimo en el que se creó un objeto para que se transfiera. Debe estar en UTC con el formato YYYY-MM-DDThh:mm:ssZ. Por ejemplo, 2024-10-14T08:30:30Z.
  
  Cualquier fecha, pasada o futura, del 0001-01-01T00:00:00Z al 9999-12-31T23:59:59Z inclusive, es válida.
- MATCH_GLOB: Especifica el patrón glob que debe coincidir para que se transfiera un objeto. Cuando usas gcloud CLI, un glob de coincidencia con caracteres * debe tener el carácter * con formato de escape en el formato \*\*.txt o todo el glob de coincidencia debe estar entre comillas "**.txt" o '**.txt'. Para obtener información sobre la sintaxis admitida en los patrones glob, consulta la documentación de Cloud Storage.

Inhabilita los registros de la plataforma

Sigue los siguientes pasos:

Console

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

Ir a temas
Haz clic en el tema de importación de Cloud Storage.
En la página de detalles del tema, haz clic en Editar.
Borra Habilitar los registros de la plataforma.
Haz clic en Actualizar.

gcloud

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.
Para evitar perder la configuración del tema de importación, asegúrate de incluirlos todos cada vez que lo actualices. Si omites algo, Pub/Sub restablece la configuración a su valor predeterminado original.

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 mencionadas en el siguiente ejemplo:
```
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
```
Reemplaza lo siguiente:
- TOPIC_ID es el ID o el nombre del tema. No se puede actualizar este campo.
- BUCKET_NAME: Especifica el nombre de un bucket existente. Por ejemplo, prod_bucket El nombre del bucket no debe incluir el ID del proyecto.
- INPUT_FORMAT: Especifica el formato de los objetos que se transfieren. Puede ser text, avro o pubsub_avro. Para obtener más información sobre estas opciones, consulta Formato de entrada.
- TEXT_DELIMITER: Especifica el delimitador con el que se dividirán los objetos de texto en mensajes de Pub/Sub. Debe ser un solo carácter y solo debe establecerse cuando INPUT_FORMAT sea text. El valor predeterminado es el carácter de salto de línea (\n).
  
  Cuando uses gcloud CLI para especificar el delimitador, presta mucha atención a la manipulación de caracteres especiales, como el carácter de línea nueva \n. Usa el formato '\n' para asegurarte de que el delimitador se interprete correctamente. Simplemente, usar \n sin comillas o sin escapar los resultados genera un delimitador de "n".
- MINIMUM_OBJECT_CREATE_TIME: Especifica el tiempo mínimo en el que se creó un objeto para que se transfiera. Debe estar en UTC con el formato YYYY-MM-DDThh:mm:ssZ. Por ejemplo, 2024-10-14T08:30:30Z.
  
  Cualquier fecha, pasada o futura, del 0001-01-01T00:00:00Z al 9999-12-31T23:59:59Z inclusive, es válida.
- MATCH_GLOB: Especifica el patrón glob que debe coincidir para que se transfiera un objeto. Cuando usas gcloud CLI, un glob de coincidencia con caracteres * debe tener el carácter * con formato de escape en el formato \*\*.txt o todo el glob de coincidencia debe estar entre comillas "**.txt" o '**.txt'. Para obtener información sobre la sintaxis admitida en los patrones glob, consulta la documentación de Cloud Storage.

Cómo ver los registros de la plataforma

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

Consola de Google Cloud

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

Ir al Explorador de registros
Selecciona un proyecto de Google Cloud.
Si es necesario, en el menú Actualizar, cambia del Visor de registros heredados a Explorador de registros.
Para filtrar tus registros de modo que solo muestren las entradas de los temas de importación de Cloud Storage, escribe resource.type="resource.type=pubsub_topic AND severity=WARNING en el campo de consulta y haz clic en Ejecutar consulta.
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 a fin de buscar registros de la plataforma sobre temas de importación de Cloud Storage, usa el comando gcloud logging read.

Especifica un filtro para limitar tus resultados a los registros de la plataforma para los temas de importación de Cloud Storage.

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.

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

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 ID del proyecto de Google Cloud.
`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/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"
}

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 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`	Es la hora en que Logging recibió la entrada de registro.