Cloud Logging para operaciones por lotes de almacenamiento

En esta página, se describe cómo configurar y ver los registros de las operaciones por lotes de almacenamiento con Cloud Logging. Un trabajo de operaciones por lotes de almacenamiento se puede configurar para generar entradas de registro de Cloud Logging para cada trabajo de transformación. Cada entrada de registro corresponde al intento de transformación de un objeto.

Las operaciones por lotes de almacenamiento admiten el registro en Cloud Logging y en los Registros de auditoría de Cloud de Cloud Storage. Si bien ambas opciones registran las acciones de las operaciones por lotes de almacenamiento, te recomendamos que uses Cloud Logging. Cloud Logging proporciona una plataforma centralizada para el análisis de registros, la supervisión en tiempo real y el filtrado avanzado, lo que ofrece una solución sólida para administrar y comprender la actividad de tus operaciones por lotes.

Antes de comenzar

Verifica que tengas acceso a Cloud Logging. Para usar Cloud Logging, recomendamos otorgar el rol de Identity and Access Management Logs Viewer (roles/logging.viewer). El rol de Logs Viewer (roles/logging.viewer) de Identity and Access Management proporciona los permisos de Identity and Access Management necesarios para ver tus datos de Cloud Logging. Para obtener más información sobre los permisos de acceso de Logging, consulta Control de acceso con IAM.

Para verificar y otorgar los permisos de IAM, completa los siguientes pasos:

Comprende los detalles del registro

Cuando el registro está habilitado, las operaciones de almacenamiento por lotes capturan los siguientes detalles:

  • Acción registrable: El valor de la acción registrable siempre es transform.

  • Estados registrables: Para cada acción, puedes elegir registrar uno o ambos de los siguientes estados:

    • SUCCEEDED: La acción se realizó correctamente.
    • FAILED: No se pudo realizar la acción.

Habilitar registro

Para habilitar el registro, especifica las acciones y los estados que se registrarán.

Línea de comandos

Cuando crees un trabajo de operaciones por lotes de almacenamiento con gcloud storage batch-operations jobs create, usa las marcas --log-actions y --log-action-states para habilitar el registro.

gcloud storage batch-operations jobs create JOB_NAME \
  --manifest-location=MANIFEST_LOCATION \
  --delete-object \
  --log-actions=transform \
  --log-action-states=LOG_ACTION_STATES

Aquí:

  • JOB_NAME es el nombre que deseas darle a tu trabajo. Por ejemplo, my-job
  • MANIFEST_LOCATION es la ubicación de tu manifiesto. Por ejemplo, gs://my-bucket/manifest.csv
  • LOG_ACTION_STATES es una lista de estados separados por comas que se registrarán. Por ejemplo, succeeded,failed

API de REST

Create a storage batch operations job con un LoggingConfig

{
   "loggingConfig": {
      "logActions": ["TRANSFORM"],
      "logActionStates": ["LOG_ACTION_STATES"],
        }
}

Aquí:

LOG_ACTION_STATES es una lista de estados separados por comas que se registrarán. Por ejemplo, "SUCCEEDED","FAILED"

Ver registros

Para ver los registros de las operaciones por lotes de almacenamiento, haz lo siguiente:

Console

  1. Ve al Google Cloud menú de navegación y selecciona Logging > Explorador de registros :<br\></br\>

    Ir al Explorador de registros.

  2. Selecciona un Google Cloud proyecto.

  3. En el menú Actualizar (Upgrade), cambia del Visor de registros heredados a Explorador de registros.

  4. Para filtrar tus registros de modo que solo muestren las entradas de operaciones por lotes de almacenamiento, escribe storage_batch_operations_job en el campo de consulta y haz clic en Ejecutar consulta.

  5. 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.

Línea de comandos

Para usar gcloud CLI a fin de buscar registros de operaciones por lotes de almacenamiento, usa el comando gcloud logging read.

Especifica un filtro para limitar tus resultados a los registros de las operaciones por lotes de almacenamiento.

gcloud logging read "resource.type=storage_batch_operations_job"

API de REST

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

Para filtrar tus resultados y que incluyan solo las entradas relacionadas con las operaciones por lotes de almacenamiento, 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=\"storage_batch_operations_job\""
}

Aquí:

my-project-name es el nombre de tu proyecto.

Formato de registro de operaciones de almacenamiento por lotes

Todos los campos específicos de las operaciones por lotes de almacenamiento se encuentran dentro de un objeto jsonPayload. Si bien el contenido exacto de jsonPayload varía según el tipo de trabajo, existe una estructura común que se comparte en todas las entradas de TransformActivityLog. En esta sección, se describen los campos de registro comunes y, luego, se detallan los campos específicos de la operación.

  • Campos de registro comunes

    Los siguientes campos aparecen en todos los registros:

    jsonPayload: {
    "@type": "type.googleapis.com/google.cloud.storagebatchoperations.logging.TransformActivityLog",
    "completeTime": "YYYY-MM-DDTHH:MM:SS.SSSSSSSSSZ",
    "status": {
      "errorMessage": "String indicating error",
      "errorType": "ENUM_VALUE",
      "statusCode": "ENUM_VALUE"
    },
    "logName": "projects/PROJECT_ID/logs/storagebatchoperations.googleapis.com%2Ftransform_activity",
    "receiveTimestamp": "YYYY-MM-DDTHH:MM:SS.SSSSSSSSSZ",
    "resource": {
      "labels": {
        "location":"us-central1",
        "job_id": "BATCH_JOB_ID",
        "resource_container": "RESOURCE_CONTAINER",
        // ... other labels
      },
      "type": "storagebatchoperations.googleapis.com/Job"
    },
    // Operation-specific details will be nested here (for example,
    // "DeleteObject", "PutObjectHold", "RewriteObject", "PutMetadata")
    // Each operation-specific object will also contain the following
    // object: "objectMetadataBefore": {
    //   "gcsObject": {
    //     "bucket": "BUCKET_NAME",
    //     "generation": "GENERATION_NUMBER",
    //     "objectKey": "OBJECT_PATH"
    //   }
    // }
    }
    

    En la siguiente tabla, se describe cada uno de los campos de registro comunes:

    Campos de registro comunes Tipo Descripción
    @type String Especifica el tipo de carga útil de la entrada de registro y, además, indica que el registro representa un TransformActivityLog para las operaciones por lotes de almacenamiento.
    completeTime Marca de tiempo La marca de tiempo compatible con ISO 8601 en la que se completó la operación.
    status Objeto Proporciona información sobre el resultado de la actividad de la operación por lotes.
    status.errorMessage String Es un mensaje de error si la operación falla. El mensaje de error solo aparece si el valor de status.statusCode no es OK.
    status.errorType String Es el tipo de error. El tipo de error solo aparece si el valor de status.statusCode no es OK.
    status.statusCode String Es el código de estado de la operación. La operación se realiza correctamente si el valor es OK. Cualquier otro valor indica una falla.
    logName String Es el nombre completo del recurso del registro, que indica el proyecto y el flujo de registro.
    receiveTimestamp Marca de tiempo Es la marca de tiempo que indica cuándo el sistema de registro recibió la entrada de registro.
    resource Objeto Es información sobre el recurso que generó la entrada de registro.
    resource.labels Objeto Son pares clave-valor que proporcionan información de identificación adicional sobre el recurso.
    resource.type String Es el tipo de recurso que generó el registro.
    objectMetadataBefore Objeto Contiene los metadatos del objeto antes de que se intentara realizar la operación por lotes.
    objectMetadataBefore.gcsObject Objeto Son los detalles sobre el objeto.
    objectMetadataBefore.gcsObject.bucket String Nombre del bucket en el que reside el objeto.
    objectMetadataBefore.gcsObject.generation String Es el número de generación del objeto antes de la operación.
    objectMetadataBefore.gcsObject.objectKey String Es la ruta de acceso completa del objeto dentro del bucket.
  • Contenido jsonPayload específico de la operación

    La diferencia entre las entradas de registro para diferentes operaciones por lotes radica en el objeto de nivel superior anidado dentro de jsonPayload. Solo uno de los siguientes objetos está disponible en una entrada de registro determinada, que corresponde a la operación por lotes específica que se realizó:

    • Borrar objeto (DeleteObject)

      jsonPayload:
      {
      "DeleteObject": {
        "objectMetadataBefore": {
          "gcsObject": {
            "bucket": "test-bucket",
            "generation": "1678912345678901",
            "objectKey": "test_object.txt"
          }
        }
        }
      }
      
    • Coloca una conservación de objetos (PutObjectHold)

      jsonPayload:
      {
      "PutObjectHold": {
        "objectMetadataBefore": {
          "gcsObject": {
            "bucket": "test-bucket",
            "generation": "1678912345678901",
            "objectKey": "test_object.txt"
          }
        },
        "temporaryHoldAfter": True,
        "eventBasedHoldAfter": True
      }
      }
      
    • Objeto de reescritura (RewriteObject)

      jsonPayload:
      {
      "RewriteObject": {
        "objectMetadataBefore": {
          "gcsObject": {
            "bucket": "test-bucket",
            "generation": "1678912345678901",
            "objectKey": "test_object.txt"
          }
        },
        "kmsKeyVersionAfter": "projects/my-gcp-project/locations/us-central1/keyRings/my-keyring-01/cryptoKeys/my-encryption-key/cryptoKeyVersions/1"
      }
      }
      
    • Metadatos de PUT (PutMetadata)

      jsonPayload:
      {
      "PutMetadata": {
        "objectMetadataBefore": {
          "gcsObject": {
            "bucket": "test-bucket",
            "generation": "1678912345678901",
            "objectKey": "test_object.txt"
          }
        },
        "content_disposition_after": "attachment; filename=\"report_final.pdf\"",
        "content_encoding_after": "gzip",
        "content_language_after": "en-US",
        "content_type_after": "application/pdf",
        "cache_control_after": "public, max-age=3600",
        "custom_time_after": "2025-06-27T10:00:00Z",
        "custom_metadata_after": {
          "project": "marketing",
          "version": "2.0",
          "approvedBy": "Admin"
        }
      }
      }
      

    En la siguiente tabla, se describen los campos de registro específicos de la operación:

    Campos de registro específicos de la operación Tipo Descripción
    PutObjectHold Objeto Indica una operación de conservación en un objeto.
    PutObjectHold.temporaryHoldAfter Booleano Si el valor es True, indica que se aplicó una conservación temporal al objeto después de que se completó el trabajo de operaciones por lotes de almacenamiento. Los valores válidos son True o False.
    PutObjectHold.eventBasedHoldAfter Booleano Si el valor es True, indica que se aplicó una conservación basada en eventos al objeto después de que se completó el trabajo de operaciones por lotes de almacenamiento. Los valores válidos son True o False.
    RewriteObject Objeto Indica una operación de reescritura en un objeto.
    RewriteObject.kmsKeyVersionAfter String Es la versión de la clave de Cloud Key Management Service que se usa después del trabajo de reescritura. El campo kmsKeyVersionAfter se completa si la clave de encriptación del objeto cambió como resultado de la reescritura. Es un campo opcional, lo que significa que podría no estar presente si la versión de la clave de Cloud KMS permaneció sin cambios después de la reescritura.
    PutMetadata Objeto Indica una operación de actualización de metadatos en un objeto.
    PutMetadata.content_disposition_after String Especifica el valor del encabezado Content-Disposition después de que se completa el trabajo PutMetadata. Es un campo opcional y solo se propaga si se estableció o modificó la disposición del contenido.
    PutMetadata.content_encoding_after String Especifica el valor del encabezado Content-Encoding después de que se completa el trabajo PutMetadata. Es un campo opcional y solo se propaga si se configuró o modificó la codificación del contenido.
    PutMetadata.content_language_after String Especifica el valor del encabezado Content-Language después de que se completa el trabajo PutMetadata. Es un campo opcional y solo se propaga si se configuró o modificó el idioma del contenido.
    PutMetadata.content_type_after String Especifica el valor del encabezado Content-Type después de que se completa el trabajo PutMetadata. Es un campo opcional y solo se propaga si se configuró o modificó el tipo de contenido.
    PutMetadata.cache_control_after String Especifica el valor del encabezado Cache-Control después de que se completa el trabajo PutMetadata. Es un campo opcional y solo se propaga si se configuró o modificó el control de caché.
    PutMetadata.custom_time_after String Especifica el valor del encabezado Custom-Time después de que se completa el trabajo PutMetadata. Es un campo opcional y solo se propaga si se estableció o modificó la hora personalizada.
    PutMetadata.custom_metadata_after Mapa (clave: cadena, valor: cadena) Contiene un mapa de pares clave-valor Custom- Metadata después de la transformación. Este campo incluye cualquier metadato definido por el usuario que se haya establecido o modificado en el objeto. Permite el almacenamiento flexible de metadatos adicionales.