Journaux d'accès et journaux de stockage

Ce document explique comment télécharger et consulter les journaux d'accès et les informations de stockage de vos buckets Cloud Storage, et analyser les journaux à l'aide de Google BigQuery.

Présentation

Cloud Storage propose des journaux d'accès et des journaux de stockage sous forme de fichiers CSV que vous pouvez télécharger et consulter. Les journaux d'accès fournissent des informations pour toutes les requêtes effectuées sur un bucket spécifié et sont créés toutes les heures. Les journaux de stockage quotidiens fournissent des informations sur l'espace de stockage consommé par ce bucket pour le jour précédent. Les journaux d'accès et de stockage sont automatiquement créés en tant que nouveaux objets dans un bucket que vous spécifiez.

Lors de la configuration d'un bucket Cloud Storage pour simuler le comportement d'un site Web statique, vous souhaiterez peut-être consigner la manière dont les ressources de ce site sont utilisées. Notez que la configuration des journaux d'accès et de stockage d'un bucket est possible, quel que soit le bucket Cloud Storage concerné.

Remarque : La rapidité de diffusion et l'exhaustivité des journaux d'accès ne sont pas garanties.

Journaux d'accès et de stockage ou Cloud Audit Logging ?

Dans la plupart des cas, les journaux d'audit Cloud constituent la méthode recommandée pour générer des journaux permettant de suivre les opérations d'API effectuées dans Cloud Storage :

• Les journaux d'audit Cloud effectuent un suivi continu des accès.
• Les journaux d'audit Cloud produisent des journaux avec lesquels il est plus facile de travailler.
• Les journaux d'audit Cloud peuvent surveiller de nombreux services Google Cloud Platform, pas seulement Cloud Storage.

Dans certains cas, l'utilisation des journaux d'accès et de stockage est préférable.

Vous souhaiterez probablement utiliser des journaux d'accès si :

• vous voulez suivre les accès aux objets publics ;
• vous voulez suivre les accès exclusifs aux objets accordés dans le cadre des listes de contrôle d'accès (LCA) définies sur les objets ;
• vous souhaitez suivre les modifications apportées par la fonctionnalité de gestion du cycle de vie des objets ;
• vous envisagez d'effectuer des téléchargements authentifiés via un navigateur pour accéder aux objets du bucket ;
• vous souhaitez que vos journaux incluent des informations de latence ou la taille de la requête et de la réponse pour des requêtes HTTP individuelles.

Vous souhaiterez probablement utiliser des journaux de stockage si :

• vous voulez suivre la quantité de données stockées dans vos buckets. Notez que ces informations, ainsi que le nombre d'objets dans un bucket, sont également disponibles dans Stackdriver.

Configurer la diffusion des journaux

Attention : Si vous utilisez ou activez le service VPC Service Controls, le bucket journalisé et le bucket qui stocke les données des journaux doivent se situer dans le même périmètre de sécurité, sans quoi la journalisation échouera.

Les étapes suivantes décrivent comment configurer la diffusion des journaux pour un bucket spécifique à l'aide de l'outil gsutil, de l'API XML et de l'API JSON. Si vous ne disposez pas de l'outil gsutil, vous pouvez le télécharger et l'installer en tant que composant du SDK Google Cloud ou en tant que produit autonome.

gsutil

1. Créez un bucket pour stocker vos journaux.

   Utilisez la commande suivante :

   gsutil mb gs://example-logs-bucket

2. Définissez les autorisations de manière à accorder à Cloud Storage l'autorisation WRITE sur le bucket.

   Cloud Storage doit disposer de l'autorisation WRITE pour pouvoir créer et stocker vos journaux en tant que nouveaux objets. Pour accorder à Cloud Storage l'accès WRITE à votre bucket, accordez au groupe [e-mail] l'accès en écriture à l'aide de la commande suivante :

   gsutil acl ch -g [e-mail]:W gs://example-logs-bucket

Les objets journaux disposeront de la LCA d'objet par défaut du bucket de journaux. Vous pouvez définir la LCA d'objet par défaut du bucket de journaux à l'aide de gsutil. Par exemple, pour définir la LCA d'objet par défaut "project-private", procédez comme suit :

gsutil defacl set project-private gs://example-logs-bucket

3. Activez la journalisation du bucket.

   Utilisez la commande logging ci-dessous :

   gsutil logging set on -b gs://example-logs-bucket [-o log_object_prefix ] gs://example-bucket

   Vous pouvez également définir le préfixe d'objet log_object_prefix pour vos objets journaux. Le préfixe d'objet constitue le début du nom de l'objet journal. Il peut contenir au maximum 900 caractères et doit être un nom d'objet valide. Par défaut, le préfixe d'objet est le nom du bucket pour lequel les journaux sont activés.

API XML

1. Créez un bucket pour stocker vos journaux.

   Envoyez la requête suivante :

   PUT /example-logs-bucket HTTP/1.1
   Host: storage.googleapis.com
   

2. Définissez les autorisations de manière à accorder à Cloud Storage l'autorisation WRITE sur le bucket.

   Cloud Storage doit disposer de l'autorisation WRITE pour pouvoir créer et stocker vos journaux en tant que nouveaux objets. Pour accorder à Cloud Storage l'accès WRITE à votre bucket, ajoutez une entrée LCA au bucket afin d'accorder l'accès en écriture au groupe [e-mail]. En plus de la nouvelle LCA, veillez à inclure dans la requête toutes les LCA existantes pour le bucket.

   PUT /example-logs-bucket?acl HTTP/1.1
   Host: storage.googleapis.com
   
   <AccessControlList>
     <Entries>
       <Entry>
         <Scope type="GroupByEmail">
           <EmailAddress>[e-mail]</EmailAddress>
         </Scope>
        <Permission>WRITE</Permission>
       </Entry>
       <!-- include other existing ACL entries here-->
     </Entries>
   </AccessControlList>
   

3. Activez la journalisation du bucket.

   Pour ce faire, spécifiez le paramètre de requête de journalisation en procédant comme suit :

   PUT /example-bucket?logging HTTP/1.1
   Host: storage.googleapis.com
   
   <Logging>
       <LogBucket>example-logs-bucket</LogBucket>
       <LogObjectPrefix>log_object_prefix</LogObjectPrefix>
   </Logging>
   

API JSON

1. Créez un bucket pour stocker vos journaux.

   Envoyez la requête suivante :

   POST /storage/v1/b?project=project-id
   Host: www.googleapis.com
   
   {
     "name": "example-logs-bucket"
   }
   

2. Définissez les autorisations de manière à accorder à Cloud Storage l'autorisation WRITE sur le bucket.

   Cloud Storage doit disposer de l'autorisation WRITE pour pouvoir créer et stocker vos journaux en tant que nouveaux objets. Pour accorder à Cloud Storage l'accès WRITE à votre bucket, ajoutez une entrée LCA au bucket afin d'accorder l'accès en écriture au groupe [e-mail]. Pour ce faire, envoyez la requête suivante à la ressource "BucketAccessControls" pour le bucket de journalisation :

   POST /storage/v1/b/example-logs-bucket/acl
   Host: www.googleapis.com
   {
    "entity": "[e-mail]",
    "role": "WRITER"
   }
   

3. Activez la journalisation du bucket.

   Envoyez la requête ci-dessous :

   PATCH /storage/v1/b/example-bucket
   Host: www.googleapis.com
   
   {
    "logging": {
     "logBucket": "example-logs-bucket",
     "logObjectPrefix": "log_object_prefix"
    }
   }
   

Vérifier l'état de la journalisation

gsutil

Pour vérifier la journalisation, utilisez la commande logging get de l'outil gsutil :

gsutil logging get gs://example-bucket

Vous pouvez également enregistrer les configurations de journalisation dans un fichier, comme indiqué ci-dessous :

gsutil logging get gs://example-bucket > your_logging_configuration_file

Si la journalisation est activée, le serveur renvoie la configuration de journalisation dans la réponse :

{"logBucket": "example-logs-bucket", "logObjectPrefix": "log_object_prefix"}

Si la journalisation n'est pas activée, les éléments suivants sont renvoyés :

gs://example-bucket/ has no logging configuration.

API XML

L'API XML de Cloud Storage permet d'envoyer une requête GET Bucket pour obtenir la configuration de journalisation du bucket, comme indiqué dans l'exemple suivant.

GET /example-bucket?logging HTTP/1.1
Host: storage.googleapis.com

Si la journalisation est activée, le serveur envoie la configuration dans la réponse, qui peut être semblable à celle-ci :

<?xml version="1.0" ?>
<Logging>
    <LogBucket>
        example-logs-bucket
    </LogBucket>
    <LogObjectPrefix>
        log_object_prefix
    </LogObjectPrefix>
</Logging>

Si la journalisation n'est pas activée, une configuration vide est renvoyée :

<?xml version="1.0" ?>
<Logging/>

API JSON

L'API JSON de Cloud Storage permet d'envoyer une requête GET pour obtenir la configuration de journalisation du bucket, comme indiqué dans l'exemple suivant.

GET /storage/v1/b/example-bucket?fields=logging
Host: www.googleapis.com

Si la journalisation est activée, le serveur envoie la configuration dans la réponse, qui peut être semblable à celle-ci :

{
 "logging": {
  "logBucket": "example-logs-bucket",
  "logObjectPrefix": "log_object_prefix"
  }
}

Si la journalisation n'est pas activée, une configuration vide est renvoyée :

{
}

Télécharger les journaux

Les journaux de stockage sont générés une fois par jour et contiennent les données d'utilisation du stockage du jour précédent. Ils sont généralement créés avant 10h00 PST.

Les journaux d'utilisation sont générés toutes les heures en cas d'activité à signaler dans le bucket surveillé. Les journaux d'utilisation sont généralement créés 15 minutes après l'heure écoulée.

Remarque :

• Pour vos tâches de traitement des journaux, notez qu'il est possible que les journaux d'utilisation soient diffusés plus de 15 minutes après l'heure écoulée.
• En général, un objet journal consignant l'utilisation horaire contient des enregistrements pour toutes les utilisations qui ont eu lieu pendant l'heure considérée. Un tel journal peut parfois contenir des enregistrements correspondant à une heure antérieure, mais jamais à une heure postérieure.
• Cloud Storage peut écrire plusieurs objets journaux pour une même heure.
• Il peut arriver qu'un enregistrement apparaisse deux fois dans les journaux d'utilisation. Nous faisons notre possible pour supprimer les enregistrements en double. Toutefois, si cela est essentiel à vos analyses, faites en sorte que vos tâches de traitement les suppriment de vos journaux. Vous pouvez utiliser le champ s_request_id pour détecter les doublons.

L'accès aux journaux est contrôlé par la LCA des objets journaux. Ceux-ci disposent de la LCA d'objet par défaut du bucket de journaux.

Le moyen le plus simple de télécharger vos journaux d'accès et de stockage consiste à utiliser la console Google Cloud Platform ou l'outil gsutil. Les journaux d'accès sont fournis au format CSV, selon la convention d'attribution de noms suivante :

gs://<bucket_name>/<object_prefix>_usage_<timestamp>_<id>_v0

Par exemple, ce qui suit est un objet "journaux d'accès" pour un bucket nommé "gs://example-bucket", créé le 18 juin 2013 à 14h00 UTC et stocké dans le bucket "gs://example-logs-bucket" :

gs://example-logs-bucket/example-bucket_usage_2013_06_18_14_00_00_1702e6_v0

Les journaux de stockage sont nommés selon la convention ci-dessous :

gs://<bucket_name>/<object_prefix>_storage_<timestamp>_<id>_v0

Voici, par exemple, un objet "journal de stockage" pour le même bucket du 18 juin 2013 :

gs://example-logs-bucket/example-bucket_storage_2013_06_18_07_00_00_1702e6_v0

Pour télécharger des journaux, procédez comme suit :

Console

1. Ouvrez le navigateur Cloud Storage dans la console Google Cloud Platform.
   Ouvrir le navigateur Cloud Storage

2. Sélectionnez votre bucket de journaux.

3. Cliquez sur l'objet journal approprié pour télécharger ou afficher les journaux.

gsutil

Exécutez la commande suivante :

gsutil cp <logs_object> <destination_uri>

Analyser des journaux dans BigQuery

Pour interroger vos journaux d'utilisation et de stockage Cloud Storage, vous pouvez utiliser Google BigQuery, qui exécute des requêtes rapides de type SQL sur des tables "à ajout seulement". L'outil de ligne de commande BigQuery, bq, est basé sur Python et permet d'accéder à BigQuery à partir de la ligne de commande. Pour en savoir plus sur le téléchargement et l'utilisation de bq, consultez la page de référence sur l'outil de ligne de commande bq.

Charger des journaux dans BigQuery

1. Sélectionnez un projet par défaut.

   Reportez-vous à la section Utiliser des projets pour en savoir plus sur la sélection d'un projet.

2. Créez un ensemble de données.

   $ bq mk storageanalysis
   Dataset 'storageanalysis' successfully created.
   

3. Répertoriez les ensembles de données dans le projet :

   $ bq ls
   
   datasetId
   -----------------
   storageanalysis
   

4. Enregistrez les schémas d'utilisation et de stockage sur votre ordinateur pour pouvoir les utiliser dans la commande de chargement.

   Ces schémas se trouvent aux emplacements cloud_storage_usage_schema_v0 et cloud_storage_storage_schema_v0. Vous en trouverez également une description à la section Format des journaux d'accès et de stockage.

5. Chargez les journaux d'accès dans l'ensemble de données.

   $ bq load --skip_leading_rows=1 storageanalysis.usage \
         gs://example-logs-bucket/example-bucket_usage_2014_01_15_14_00_00_1702e6_v0 \
         ./cloud_storage_usage_schema_v0.json
   $ bq load --skip_leading_rows=1 storageanalysis.storage \
         gs://example-logs-bucket/example-bucket_storage_2014_01_05_14_00_00_091c5f_v0 \
         ./cloud_storage_storage_schema_v0.json
   

   Ces commandes permettent d'exécuter les opérations suivantes :

   • Charger les journaux d'utilisation et de stockage à partir du bucket example-logs-bucket
   • Créer les tables usage et storage dans l'ensemble de données storageanalysis
   • Lire les données de schéma (fichier .json) dans le même répertoire que celui où la commande bq est exécutée
   • Ignorer la première ligne de chaque fichier journal qui contient les descriptions de colonne

   Comme, dans cet exemple, c'est la première fois que vous exécutez la commande de chargement, les tables usage et storage ont été créées. Vous pouvez continuer à ajouter d'autres commandes de chargement à ces tables avec des noms de fichiers journaux d'accès différents ou en utilisant des caractères génériques. Par exemple, la commande suivante ajoute les données de tous les journaux commençant par "bucket_usuage_2014" à la table storage :

   $ bq load --skip_leading_rows=1 storageanalysis.usage \
         gs://example-logs-bucket/bucket_usage_2014* \
         ./cloud_storage_usage_schema.json
   

   Lorsque vous utilisez des caractères génériques, vous pouvez déplacer les journaux déjà importés dans BigQuery vers un autre répertoire (par exemple, gs://example-logs-bucket/processed) pour éviter d'importer plusieurs fois les données d'un journal.

La fonctionnalité BigQuery est également accessible via l'interface Web de BigQuery. Cet outil vous permet de charger des données via le processus de création de table.

Pour en savoir plus sur le chargement de données depuis Cloud Storage, y compris de manière automatisée, consultez la section Charger des données à partir de Cloud Storage.

Modifier le schéma d'un journal d'accès

Dans certains scénarios, il peut être utile de prétraiter les journaux d'accès avant de les charger dans BigQuery. Par exemple, vous pouvez ajouter des informations aux journaux d'accès pour faciliter l'analyse de requêtes dans BigQuery. Dans cette section, nous verrons comment ajouter au journal le nom de fichier de chaque journal d'accès au stockage. Pour cela, il est nécessaire de modifier le schéma existant ainsi que chaque fichier journal.

1. Modifiez le schéma existant, cloud_storage_storage_schema_v0, de manière à ajouter le nom du fichier, comme indiqué ci-dessous. Attribuez un nom au nouveau schéma, par exemple cloud_storage_storage_schema_custom.json, afin de le distinguer de l'original.

   [  {"name": "bucket", "type": "string", "mode": "REQUIRED"},
   {"name": "storage_byte_hours","type": "integer","mode": "REQUIRED"},
   {"name": "filename","type": "string","mode": "REQUIRED"}
   ]
   

2. Prétraitez les fichiers des journaux d'accès au stockage basés sur le nouveau schéma avant de les charger dans BigQuery.

   Par exemple, dans les environnements Linux, macOS ou Windows (Cygwin), vous pouvez utiliser les commandes ci-dessous :

   gsutil cp gs://example-logs-bucket/example-bucket_storage\* .
   for f in example-bucket_storage\*; do sed -i -e "1s/$/,\"filename\"/" -e "2s/$/,\""$f"\"/" $f; done
   

   La commande gsutil copie les fichiers dans votre répertoire de travail. La deuxième commande parcourt les fichiers journaux, et ajoute "filename" à la ligne de description (première ligne) et le nom de fichier actuel à la ligne de données (deuxième ligne). Voici un exemple de fichier journal modifié :

   "bucket","storage_byte_hours","filename"
   "example-bucket","5532482018","example-bucket_storage_2014_01_05_08_00_00_021fd_v0"
   

3. Lorsque vous chargez les journaux d'accès au stockage dans BigQuery, chargez vos journaux modifiés localement et utilisez le schéma personnalisé.

   for f in example-bucket_storage\*; \
   do ./bq.py load --skip_leading_rows=1 storageanalysis.storage $f ./cloud_storage_storage_schema_custom.json; done
   

Interroger des journaux dans BigQuery

Une fois les journaux chargés dans BigQuery, vous pouvez interroger vos journaux d'accès pour obtenir des informations sur votre ou vos buckets de journalisation. L'exemple suivant montre comment utiliser l'outil bq pour interroger les journaux représentant plusieurs jours d'accès à un bucket, que vous avez chargés comme indiqué à la section Charger des journaux d'accès dans BigQuery. Vous pouvez également exécuter les requêtes ci-dessous depuis l'interface Web de BigQuery.

1. Activez le mode interactif dans l'outil bq.

   $ bq shell
   

2. Exécutez une requête sur la table de journaux de stockage.

   Par exemple, la requête suivante montre comment le stockage d'un bucket journalisé évolue dans le temps. Cela suppose que vous avez modifié les journaux d'accès au stockage, comme décrit à la section Modifier le schéma d'un journal d'accès, et que les fichiers journaux sont nommés "logstorage*".

   project-name>SELECT SUBSTRING(filename, 13, 10) as day, storage_byte_hours/24 as size FROM [storageanalysis.storage] ORDER BY filename LIMIT 100
   

   Exemple de résultat de la requête :

   Waiting on bqjob_r36fbf5c164a966e8_0000014379bc199c_1 ... (0s) Current status: DONE
   +------------+----------------------+
   |    day     |         size         |
   +------------+----------------------+
   | 2014_01_05 | 2.3052008408333334E8 |
   | 2014_01_06 | 2.3012297245833334E8 |
   | 2014_01_07 | 3.3477797120833334E8 |
   | 2014_01_08 | 4.4183686058333334E8 |
   +-----------------------------------+
   

   Si vous n'avez pas modifié le schéma et que vous utilisez celui par défaut, vous pouvez exécuter la requête ci-dessous :

   project-name>SELECT storage_byte_hours FROM [storageanalysis.storage] LIMIT 100
   

3. Exécutez une requête sur la table de journaux d'utilisation.

   Par exemple, la requête suivante montre comment récapituler les méthodes de requête que les clients utilisent pour accéder aux ressources du bucket journalisé.

   project-name>SELECT cs_method, COUNT(\*) AS count FROM [storageanalysis.usage] GROUP BY cs_method
   

   Exemple de résultat de la requête :

   Waiting on bqjob_r1a6b4596bd9c29fb_000001437d6f8a52_1 ... (0s) Current status: DONE
   +-----------+-------+
   | cs_method | count |
   +-----------+-------+
   | PUT       |  8002 |
   | GET       | 12631 |
   | POST      |  2737 |
   | HEAD      |  2173 |
   | DELETE    |  7290 |
   +-----------+-------+
   

4. Quittez l'interface système interactive de l'outil bq.

   project-name> quit
   

Désactiver la journalisation

gsutil

Dans l'outil gsutil, désactivez la journalisation à l'aide de la commande logging :

gsutil logging set off gs://example-bucket

Pour vérifier que la journalisation a bien été désactivée, exécutez une requête logging get :

gsutil logging get gs://example-bucket

Si la journalisation est désactivée, les éléments suivants sont renvoyés :

gs://example-bucket/ has no logging configuration.

API XML

À l'aide de l'API XML de Cloud Storage, désactivez la journalisation en envoyant une requête PUT à la configuration de journalisation du bucket, comme indiqué dans l'exemple ci-dessous :

PUT /example-bucket?logging HTTP/1.1
Host: storage.googleapis.com

<Logging/>

API JSON

À l'aide de l'API JSON de Cloud Storage, désactivez la journalisation en envoyant une demande PATCH à la configuration de journalisation du bucket, comme indiqué dans l'exemple ci-dessous :

PATCH /example-bucket?logging HTTP/1.1
Host: storage.googleapis.com

{
 "logging": null
}

Format des journaux d'accès et de stockage

Les journaux d'accès et de stockage peuvent fournir une quantité accablante d'informations. Pour vous aider à déterminer la nature de toutes ces informations, consultez les tableaux ci-après.

Champs de journal d'accès :

Champ	Type	Description
time_micros	entier	Heure à laquelle la requête a été effectuée, exprimée en microsecondes depuis l'époque Unix.
c_ip	chaîne	Adresse IP à partir de laquelle la requête a été envoyée. Le préfixe "c" indique qu'il s'agit d'informations sur le client.
c_ip_type	entier	Type d'IP dans le champ "c_ip" : Une valeur de 1 indique une adresse IPV4. Une valeur de 2 indique une adresse IPV6.
c_ip_region	chaîne	Réservé pour une utilisation ultérieure.
cs_method	chaîne	Méthode HTTP de cette requête. Le préfixe "cs" indique que cette information a été envoyée du client au serveur.
cs_uri	chaîne	URI de la requête.
sc_status	entier	Code d'état HTTP envoyé par le serveur en réponse. Le préfixe "sc" indique que cette information a été envoyée du serveur au client.
cs_bytes	entier	Nombre d'octets envoyés dans la requête.
sc_bytes	entier	Nombre d'octets envoyés dans la réponse.
time_taken_micros	entier	Délai de réponse à la requête en microsecondes, mesuré à partir du moment où le premier octet est reçu jusqu'au moment où la réponse est envoyée. Notez que pour les importations avec reprise, le point final est déterminé par la réponse à la requête d'importation finale faisant partie de l'importation avec reprise.
cs_host	chaîne	Hôte dans la requête d'origine.
cs_referer	chaîne	Référent HTTP de la requête.
cs_user_agent	chaîne	User-agent de la requête. La valeur est GCS Lifecycle Management pour les requêtes effectuées par la fonctionnalité de gestion du cycle de vie.
s_request_id	chaîne	Identifiant de la requête.
cs_operation	chaîne	Opération Cloud Storage, par exemple GET_Object.
cs_bucket	chaîne	Bucket spécifié dans la requête. S'il s'agit d'une requête pour répertorier les buckets, la valeur peut être nulle.
cs_object	chaîne	Objet spécifié dans cette requête. La valeur peut être nulle.

Champs de journal de stockage :

Champ	Type	Description
bucket	chaîne	Nom du bucket.
storage_byte_hours	entier	Taille moyenne du bucket en octets par heure sur une période de 24 heures. Pour obtenir la taille totale du bucket, divisez le nombre d'octets à l'heure par 24.