Journaux d'utilisation et journaux de stockage

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

Introduction

Cloud Storage propose des journaux d'utilisation et des journaux de stockage sous forme de fichiers CSV que vous pouvez télécharger et consulter. Les journaux d'utilisation 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 fournissent des informations sur l'espace de stockage consommé par ce bucket pour le jour précédent et sont créés quotidiennement.

Une fois configurés, les journaux d'utilisation et de stockage sont automatiquement créés en tant que nouveaux objets dans un bucket que vous spécifiez.

Les journaux d'utilisation et de stockage sont soumis aux mêmes tarifs que les autres objets stockés dans Cloud Storage.

Faut-il utiliser des journaux d'utilisation ou des journaux d'audit Cloud ?

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, avec la livraison d'événements dans les secondes qui suivent leur occurrence.
  • Les journaux d'audit Cloud produisent des journaux avec lesquels il est plus facile de travailler.
  • Les journaux d'audit Cloud permettent de surveiller de nombreux services Google Cloud, pas seulement Cloud Storage.
  • Les journaux d'audit Cloud peuvent éventuellement fournir des informations détaillées sur les requêtes et les réponses.

Dans certains cas, vous pouvez utiliser des journaux d'utilisation à la place ou en plus de Cloud Audit Logs. Vous souhaiterez probablement utiliser des journaux d'utilisation si :

  • Vous souhaitez suivre l'accès qui se produit car une ressource a allUsers ou allAuthenticatedUsers dans ses paramètres de contrôle d'accès, comme l'accès aux éléments d'un bucket que vous avez configuré pour être un site Web statique.
  • vous souhaitez suivre les modifications apportées par la fonctionnalité de gestion du cycle de vie des objets ou de classe automatique ;
  • 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, la taille de la requête et de la réponse pour des requêtes HTTP individuelles, ou le chemin d'URL complet et chaque paramètre de requête.
  • Vous souhaitez suivre l'accès à certains buckets uniquement dans votre projet et ne souhaitez donc pas activer les journaux d'audit pour l'accès aux données, qui suivent l'accès à tous les buckets de votre projet.

Notez que les journaux d'utilisation ne sont générés qu'une fois par heure et peuvent être retardés, en particulier lors de la création de rapports sur les buckets soumis à des taux de requêtes élevés.

Faut-il utiliser des journaux de stockage ou Monitoring ?

D'une manière générale, vous ne devez pas utiliser les journaux de stockage. L'outil recommandé pour mesurer l'espace de stockage consommé est Monitoring. Contrairement aux journaux de stockage, il fournit des outils de visualisation ainsi que des métriques supplémentaires concernant l'utilisation de l'espace de stockage. Pour obtenir des instructions détaillées sur l'utilisation de Monitoring, consultez la section Déterminer la taille d'un bucket de l'onglet "Console".

Configurer la diffusion des journaux

Lorsque vous configurez la diffusion des journaux, les journaux d'utilisation et de stockage sont générés pour le bucket spécifié. Les étapes suivantes décrivent comment configurer la diffusion des journaux pour un bucket. Si vous ne disposez pas déjà d'un bucket que vous prévoyez d'utiliser pour stocker des journaux, créez le bucket.

Ligne de commande

  1. Attribuez le rôle roles/storage.objectCreator à Cloud Storage pour le bucket.

    gcloud storage buckets add-iam-policy-binding gs://example-logs-bucket --member=group:cloud-storage-analytics@google.com --role=roles/storage.objectCreator

    Le rôle accorde à Cloud Storage, sous la forme du groupe cloud-storage-analytics@google.com, l'autorisation de créer et de stocker vos journaux en tant que nouveaux objets.

    Les objets journaux disposent de la LCA d'objet par défaut du bucket de journaux, sauf si l'accès uniforme au niveau du bucket est activé sur ce bucket.

  2. Activer la journalisation pour votre bucket à l'aide de l'option --log-bucket

    gcloud storage buckets update gs://example-bucket --log-bucket=gs://example-logs-bucket [--log-object-prefix=log_object_prefix]

    Si vous le souhaitez, vous pouvez définir un préfixe d'objet pour vos objets journaux en utilisant l'option --log-object-prefix. 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 REST

API JSON

  1. Attribuez le rôle roles/storage.objectCreator à Cloud Storage pour le bucket. S'il existe d'autres liaisons IAM au niveau du bucket, veillez à les inclure dans la requête.

    POST /storage/v1/b/example-logs-bucket/iam
Host: storage.googleapis.com
{
  "bindings":[
    {
      "role": "roles/storage.objectCreator",
      "members":[
        "group-cloud-storage-analytics@google.com"
      ]
    }
  ]
}

    Le rôle accorde à Cloud Storage, sous la forme du groupe cloud-storage-analytics@google.com, l'autorisation de créer et de stocker vos journaux en tant que nouveaux objets.

    Les objets journaux disposent de la LCA d'objet par défaut du bucket de journaux, sauf si l'accès uniforme au niveau du bucket est activé sur ce bucket.

  2. Activez la journalisation pour votre bucket à l'aide de la requête suivante :

    PATCH /storage/v1/b/example-bucket
Host: storage.googleapis.com

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

API XML

  1. Définissez les autorisations de manière à accorder à Cloud Storage l'autorisation WRITE sur le bucket. Cela vous permettra de créer et de stocker vos journaux en tant que nouveaux objets. Vous devez ajouter une entrée de LCA au bucket afin d'accorder l'accès en écriture au groupe cloud-storage-analytics@google.com. 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>cloud-storage-analytics@google.com</EmailAddress>
      </Scope>
     <Permission>WRITE</Permission>
    </Entry>
    <!-- include other existing ACL entries here-->
  </Entries>
</AccessControlList>

  2. Activez la journalisation pour votre bucket à l'aide du paramètre de requête de journalisation :

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

<Logging>
    <LogBucket>example-logs-bucket</LogBucket>
    <LogObjectPrefix>log_object_prefix</LogObjectPrefix>
</Logging>

Vérifier l'état de la journalisation

Ligne de commande

Vérifiez la journalisation à l'aide de la commande buckets describe avec l'option --format :

gcloud storage buckets describe gs://example-bucket --format="default(logging_config)"

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

gcloud storage buckets describe gs://example-bucket > your_logging_configuration_file --format="default(logging_config)"

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

logging:
  logBucket: example-logs-bucket
  logObjectPrefix: log_object_prefix

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

null

API REST

API JSON

Envoyez 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: storage.googleapis.com

Si la journalisation est activée, le serveur envoie la configuration dans la réponse. La réponse peut ressembler à la suivante :

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

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

{}

API XML

Envoyez 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. La réponse peut ressembler à la suivante :

<?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/>

Télécharger les journaux

Les journaux de stockage sont générés une fois par jour et contiennent la quantité de stockage utilisée le 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.

Le moyen le plus simple de télécharger vos journaux d'utilisation et de stockage à partir du bucket dans lequel ils sont stockés consiste à utiliser l'une des méthodes suivantes : console Google Cloud ou CLI gcloud storage. Les journaux d'utilisation sont fournis au format CSV, selon la convention d'attribution de noms suivante :

OBJECT_PREFIX_usage_TIMESTAMP_ID_v0

De même, les journaux de stockage sont nommés selon la convention ci-dessous :

OBJECT_PREFIX_storage_TIMESTAMP_ID_v0

Par exemple, ce qui suit est le nom d'un objet journal d'utilisation qui utilise le préfixe d'objet par défaut, signale l'utilisation du bucket nommé example-bucket et a été créée le 18 juin 2022 à 14h UTC :

example-bucket_usage_2022_06_18_14_00_00_1702e6_v0

De même, le nom de l'objet de journal de stockage utilisant le préfixe d'objet par défaut a été créé le 18 juin 2022 pour ce même bucket:

example-bucket_storage_2022_06_18_07_00_00_1702e6_v0

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

Console

  1. Dans la console Google Cloud, accédez à la page Buckets Cloud Storage.

    Accéder à la page "Buckets"

  2. Sélectionnez le bucket dans lequel vos journaux sont stockés.

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

Ligne de commande

Exécutez la commande ci-dessous.

gcloud storage cp gs://BUCKET_NAME/LOGS_OBJECT DESTINATION

Où :

  • BUCKET_NAME est le nom du bucket dans lequel les journaux sont stockés. Par exemple, example-logs-bucket.

  • LOGS_OBJECT est le nom du journal d'utilisation ou du journal de stockage que vous téléchargez. Exemple : example-bucket_usage_2022_06_18_14_00_00_1702e6_v0.

  • DESTINATION est l'emplacement dans lequel le journal est téléchargé. Par exemple, Desktop/Logs.

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 un outil basé sur Python qui 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'utilisation et de stockage.

  5. Chargez les journaux d'utilisation 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 des 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

    Dans cet exemple, comme 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'utilisation 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 des journaux d'utilisation

Dans certains scénarios, il peut être utile de prétraiter les journaux d'utilisation avant de les charger dans BigQuery. Par exemple, vous pouvez ajouter des informations aux journaux d'utilisation 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'utilisation 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'utilisation de l'espace de 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 :

    gcloud storage 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 gcloud storage 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'utilisation du 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'utilisation pour obtenir des informations sur votre ou vos buckets de journalisation. L'exemple suivant montre comment utiliser l'outil bq pour quand vous avez des journaux d'utilisation pour un bucket sur plusieurs jours et que vous les avez chargés comme indiqué à la section Charger des journaux d'utilisation dans BigQuery Vous pouvez également exécuter les requêtes ci-dessous à l'aide de l'outil de navigation 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'utilisation du stockage, comme décrit à la section Modifier le schéma des journaux d'utilisation, 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 le shell interactif de l'outil bq.

    project-name> quit

Désactiver la journalisation

Ligne de commande

Désactivez la journalisation avec l'option --clear-log-bucket dans la commande buckets update :

gcloud storage buckets update gs://example-bucket --clear-log-bucket

Pour vérifier que la journalisation a bien été désactivée, utilisez la commande buckets describe :

gcloud storage buckets describe gs://example-bucket --format="default(logging_config)"

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

null

API REST

API JSON

Désactivez la journalisation en envoyant une requête PATCH à la configuration de journalisation du bucket, comme indiqué dans l'exemple suivant.

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

{
 "logging": null
}

API XML

Désactivez la journalisation en envoyant une requête PUT à la configuration de journalisation du bucket, comme indiqué dans l'exemple suivant :

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

<Logging/>

Format des journaux d'utilisation et de stockage

Les journaux d'utilisation 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'utilisation :

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'adresse 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. La valeur peut être nulle.
cs_bucket string Bucket spécifié dans la requête.
cs_object string 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.