Activer la journalisation pour le service de transfert de stockage

Cette page explique comment configurer le service de transfert de stockage pour générer des données de journal qui enregistrent les actions et les états. Vous pouvez afficher et analyser les données de journal à l'aide de Cloud Logging.

Le service de transfert de stockage peut générer des données de journal pour tous les transferts. Toutefois, les opérations FIND ne sont pas journalisées pour les transferts basés sur un agent.

Les transferts de systèmes de fichiers peuvent également configurer des journaux de transfert de systèmes de fichiers.

Avant de commencer

Avant de commencer, vérifiez que vous avez accès à Cloud Logging. Nous vous recommandons le rôle Identity and Access Management (IAM) de lecteur de journaux (roles/logging.viewer). Pour en savoir plus sur l'accès à Logging, consultez la section Contrôle des accès avec IAM.

Les documents suivants expliquent comment vérifier votre accès actuel et comment attribuer des rôles IAM :

Actions pouvant être consignées

Les actions suivantes peuvent être consignées :

  • FIND: recherche de tâches à effectuer, comme répertorier les fichiers d'un répertoire, les objets d'un bucket ou les dossiers gérés d'un bucket. Non compatible avec les transferts basés sur un agent.
  • COPY : copie de fichiers ou d'objets vers Cloud Storage.
  • DELETE : suppression de fichiers ou d'objets de la source ou de la destination. Pour les transferts entre deux systèmes de fichiers, consigne également la suppression des fichiers du bucket Cloud Storage intermédiaire.

États pouvant être consignés

Pour chaque action, vous pouvez également enregistrer un ou plusieurs des états suivants :

  • SUCCEEDED : l'action a réussi.
  • FAILED : l'action a échoué.
  • SKIPPED: ne s'applique qu'à l'action COPY et n'est compatible qu'avec les tâches de transfert basées sur un agent. Doit être défini à l'aide de gcloud ou de l'API REST. Cet état signifie que la copie a été ignorée. Cela se produit lorsque le fichier existe déjà dans le récepteur et que votre tâche de transfert est configurée pour ignorer les fichiers existants.

Bonnes pratiques

L'activation de la journalisation pour l'action FIND ou pour l'état SUCCEEDED peut entraîner un volume élevé de données de journal, ce qui peut avoir une incidence sur vos coûts Cloud Logging.

Vous pouvez utiliser les stratégies suivantes pour réduire le volume de données de journal stockées :

  • Ne consigner que les échecs. Si vous n'avez pas besoin d'un audit de conformité complet au niveau de l'objet, configurez la tâche pour qu'elle n'écrive des journaux que pour les actions de copie et de suppression, et uniquement en cas d'échec.

  • Utilisez des données de métriques pour surveiller le débit, le nombre d'octets et les objets ignorés ou ayant échoué. Vous pouvez créer des graphiques et surveiller les données de métriques à l'aide d'une règle d'alerte. Pour obtenir la liste des métriques disponibles, consultez la section Service de transfert de stockage.

  • Configurez Cloud Logging pour qu'il ignore les données de journal à volume élevé et à faible valeur. Pour effectuer cette modification, mettez à jour les récepteurs de journaux de votre projet afin d'exclure les données de journal du service de transfert de stockage à faible valeur. Étant donné que tous les récepteurs de journaux d'un projet évaluent toutes les entrées de journal, vous devrez peut-être mettre à jour plusieurs récepteurs de journaux.

    Utilisez le filtre d'exclusion suivant pour exclure les entrées de journal du service de transfert de stockage qui enregistrent les actions réussies :

    resource.type="storage_transfer_job" AND
jsonPayload.status.statusCode="OK"

    Pour savoir comment trouver et modifier vos récepteurs de journaux, consultez la section Acheminer les journaux vers des destinations compatibles.

Activer la journalisation

Pour configurer le service de transfert de stockage afin qu'il génère des données de journal, spécifiez les actions et les états à consigner.

gcloud CLI

Lorsque vous créez une tâche de transfert avec gcloud transfer jobs create, utilisez les flags suivants pour activer la journalisation :

gcloud transfer jobs create SOURCE DESTINATION \
  --log-actions=copy,delete,find \
  --log-action-states=succeeded,failed,skipped

Vous devez spécifier au moins une valeur pour chaque flag.

REST

Pour créer une configuration de journalisation, utilisez transferJobs.create avec un élément LoggingConfig :

{
  "name":"transferJobs/myFirstTransfer",
  "status": "ENABLED",
  "projectId": "test-id-001",
  "loggingConfig": {
     "logActions": ["FIND", "DELETE", "COPY"],
     "logActionStates": ["SUCCEEDED", "FAILED", "SKIPPED"], #SKIPPED is only supported for agent-based transfers
  },
  "transferSpec": {
      "awsS3DataSource": {
          "bucketName": "AWS_SOURCE_NAME",
          "awsAccessKey": {
              "accessKeyId": "AWS_ACCESS_KEY_ID",
              "secretAccessKey": "AWS_SECRET_ACCESS_KEY"
          }
      },
      "gcsDataSink": {
           "bucketName": "destination_bucket",
           "path": "foo/bar/"
      },
   }
}

Ajustez loggingConfig pour inclure les logActions et logActionStates spécifiques à consigner. Par exemple, pour consigner les échecs des actions de copie et de recherche, fournissez la loggingConfig suivante :

"loggingConfig": {
  "logActions": ["COPY", "FIND"],
  "logActionStates": ["FAILED"],
}

Mettre à jour une configuration de journalisation

gcloud CLI

Pour mettre à jour la configuration de journalisation d'une tâche existante, utilisez les flags appropriés avec la gcloud transfer jobs update commande :

gcloud transfer jobs update NAME \
  --log-actions=copy,delete,find \
  --log-action-states=succeeded,failed,skipped

Pour désactiver la journalisation pour cette tâche, spécifiez --clear-log-config :

gcloud transfer jobs update NAME --clear-log-config

REST

Pour mettre à jour la configuration de journalisation d'une tâche de transfert existante, utilisez transferJobs.patch avec LoggingConfig :

{
  "projectId": "test-id-001",
  "transferJob": {
    "loggingConfig": {
       "logActions": ["FIND", "DELETE", "COPY"],
       "logActionStates": ["SUCCEEDED", "FAILED", "SKIPPED"], #SKIPPED is only supported for agent-based transfers
    },
  },
  "updateTransferJobFieldMask": "loggingConfig"
}

updateTransferJobFieldMask spécifie le champ mis à jour dans cette requête et est obligatoire.

Pour désactiver la journalisation pour cette tâche, envoyez une loggingConfig avec des listes vides pour logActions et logActionStates :

{
  "projectId": "test-id-001",
  "transferJob": {
    "loggingConfig": {
       "logActions": [],
       "logActionStates": [],
    },
  },
  "updateTransferJobFieldMask": "loggingConfig"
}

Afficher les journaux

Pour afficher les journaux de transfert, procédez comme suit :

Google Cloud console

  1. Accédez au menu de navigation Google Cloud , puis sélectionnez Journalisation > Explorateur de journaux :

    Accéder à l'explorateur de journaux

  2. Sélectionnez un projet Google Cloud .

  3. Dans le menu Mettre à niveau, passez de l'ancienne visionneuse de journaux à l'explorateur de journaux.

  4. Pour filtrer vos journaux afin de n'afficher que les entrées du service de transfert de stockage, saisissez storage_transfer_job dans le champ de requête, puis cliquez sur Exécuter la requête.

  5. Dans le volet Résultats de la requête, cliquez sur Modifier l'heure pour modifier la période pendant laquelle les résultats doivent être renvoyés.

Pour en savoir plus sur l'utilisation de l'explorateur de journaux, consultez la page Utiliser l' explorateur de journaux.

gcloud CLI

Pour rechercher des journaux du service de transfert de stockage à l'aide de la CLI gcloud, utilisez la commande gcloud logging read.

Spécifiez un filtre pour limiter les résultats aux journaux du service de transfert de stockage.

gcloud logging read "resource.type=storage_transfer_job"

API Cloud Logging

Utilisez la méthode API Cloud Logging entries.list.

Pour filtrer vos résultats afin de n'inclure que les entrées liées au service de transfert de stockage, utilisez le champ filter. Vous trouverez ci-dessous un exemple d'objet de requête JSON.

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

Format du journal de transfert

La section suivante décrit les champs des journaux du service de transfert de stockage :

Tous les champs spécifiques au service de transfert de stockage sont contenus dans un objet jsonPayload.

Actions FIND 

{
  "jsonPayload": {
    "@type": "type.googleapis.com/google.storagetransfer.logging.TransferActivityLog",
    "action": "FIND",
    "completeTime": "2021-12-16T18:58:49.344509695Z",
    "destinationContainer": {
      "gcsBucket": {
        "bucket": "my-bucket-2",
      },
      "type": "GCS",
    },
    "operation": "transferOperations/transferJobs-7876027868280507149--3019866490856027148",
    "sourceContainer": {
      "gcsBucket": {
        "bucket": "my-bucket-1"
      },
      "type": "GCS"
    },
    "status": {
      "statusCode": "OK"
    }
  }
}

Actions COPY et DELETE

{
  "jsonPayload": {
    "@type": "type.googleapis.com/google.storagetransfer.logging.TransferActivityLog",
    "action": "COPY",
    "completeTime": "2021-12-16T18:59:00.510509049Z",
    "destinationObject": {
      "gcsObject": {
        "bucket": "my-bucket-2",
        "objectKey": "README.md"
      },
      "type": "GCS",
    },
    "operation": "transferOperations/transferJobs-7876027868280507149--3019866490856027148",
    "sourceObject": {
      "gcsObject": {
        "bucket": "my-bucket-1",
        "lastModifiedTime": "2021-12-07T16:41:09.456Z",
        "md5": "WgnCOIdfCXNTUDpQJSKb2w==",
        "objectKey": "README.md",
      },
      "type": "GCS",
    },
    "status": {
      "statusCode": "OK"
    }
  }
}
Champ du journal Description
@type La valeur est toujours type.googleapis.com/google.storagetransfer.logging.TransferActivityLog.
action

Décrit l'action de cette tâche particulière. Choisissez l'une des options suivantes :

  • FIND : recherche de tâches à effectuer, comme répertorier les fichiers d'un répertoire ou les objets d'un bucket. Non compatible avec les transferts basés sur un agent.
  • COPY : copie de fichiers ou d'objets vers Cloud Storage.
  • DELETE : suppression de fichiers ou d'objets de la source, destination ou du bucket intermédiaire.
findAction

Indique si l'objet de l'action de recherche était un objet ou un dossier géré.
completeTime Code temporel conforme à la norme ISO 8601 indiquant quand l'opération s'est terminée.
destinationContainer

Uniquement présent pour les opérations FIND. Les opérations FIND ne sont pas journalisées pour les transferts basés sur un agent.

Conteneur de destination pour ce transfert. Contient deux sous-champs :

  • gcsBucket.bucket : le nom du bucket Cloud Storage de destination.
  • type : toujours GCS.
destinationObject

Uniquement présent pour les opérations COPY et DELETE.

Informations sur l'objet de destination. Contient deux sous-champs :

  • L'une des options suivantes : gcsObject, gcsManagedFolder, ou posixFile, selon la destination. Toutes les options contiennent plusieurs sous-champs qui spécifient le nom, l'emplacement, les informations de date/heure info, et le hachage de l'objet ou du fichier.
  • type correspond à GCS ou POSIX_FS.

Exemple :

"destinationObject": {
  "type": "POSIX_FS",
  "posixFile": {
    "crc32c": "0",
    "path": "/tmp/data/filename.txt",
    "lastModifiedTime": "2022-09-22T04:33:45Z"
  }
}
operation Le nom complet de transferOperations.
sourceContainer

Uniquement présent pour les opérations FIND. Les opérations FIND ne sont pas journalisées pour les transferts basés sur un agent.

Le conteneur source pour ce transfert. Contient deux sous-champs :

  • Une entrée spécifiant l'emplacement source. Le nom du champ dépend du type de source. Les champs possibles sont les suivants.
    • awsS3Bucket.bucket : nom du bucket AWS S3.
    • azureBlobContainer : contient les sous-champs account et container, qui définissent ensemble l'URI de stockage Microsoft Azure Blob.
    • gcsBucket.bucket : le nom du bucket Cloud Storage.
    • httpManifest.url : l'URL d'une liste d'URL spécifiant les fichiers accessibles au public à télécharger depuis un serveur HTTP(S).
  • type correspond à AWS_S3, AZURE_BLOB, GCS ou HTTP.

Exemple :

"sourceContainer": {
  "gcsBucket": {
    "bucket": "my-bucket-1"
  },
  type: "GCS"
}
sourceObject

Uniquement présent pour les opérations COPY et DELETE.

Informations sur l'objet source. Contient deux sous-champs :

  • Une entrée spécifique à l'hôte de l'objet source. Le champ est nommé en fonction du type de source et contient des sous-champs pour les métadonnées. Les champs possibles sont les suivants.
    • awsS3Object : un objet AWS S3.
    • azureBlob : un fichier dans Azure Blob Storage.
    • gcsObject : un objet Cloud Storage.
    • gcsManagedFolder : un dossier géré Cloud Storage.
    • httpFile : un fichier spécifié par une liste d'URL.
    • posixFile : un fichier sur un système de fichiers POSIX.
  • type correspond à AWS_S3, AZURE_BLOB, GCS, HTTP ou POSIX_FS.

Exemple :

"sourceObject": {
  "gcsObject": {
    "bucket": "my-bucket-1"
    "lastModifiedTime": "2021-12-07T16:41:09.456Z"
    "md5": "WgnCOIdfCXNTUDpQJSKb2w=="
    "objectKey": "README.md"
  },
  type: "GCS"
}
status

L'état de l'action. Si la valeur de status.statusCode est OK, l'action a réussi. Sinon, l'action a échoué. Les champs status.errorType et status.errorMessage ne sont renseignés que si l'état n'est pas OK.

De plus, le champ de niveau supérieur resource contient les champs suivants.

"resource": {
  "labels": {
    "job_id": "transferJobs/7876027868280507149"
    "project_id": "my-project-id"
  },
  "type": "storage_transfer_job"
}
Champ du journal Description
resource.labels.job_id Le nom de la tâche du service de transfert de stockage à laquelle appartient ce journal.
resource.labels.project_id L'ID de projet Google Cloud pour ce transfert.