Améliorer le temps de requête avec l'indexation personnalisée

Ce document explique comment ajouter des champs LogEntry indexés à vos buckets Cloud Logging pour accélérer l'interrogation de vos données de journaux.

Présentation

Les performances des requêtes sont essentielles pour toute solution de journalisation. À mesure que les charges de travail augmentent et que les volumes de journaux correspondants augmentent, l'indexation de vos données de journaux les plus utilisées peut réduire le temps de requête.

Pour améliorer les performances des requêtes, Logging indexe automatiquement les champs LogEntry suivants :

Outre les champs que Logging indexe automatiquement, vous pouvez également demander à un bucket de journaux d'indexer d'autres LogEntry champs en créant un index personnalisé pour le bucket.

Supposons par exemple que vos expressions de requête incluent souvent le champ jsonPayload.request.status. Vous pouvez configurer un index personnalisé pour un bucket qui inclut jsonPayload.request.status. Toute requête ultérieure sur les données de ce bucket fera référence aux données jsonPayload.request.status indexées si l'expression de requête inclut ce champ.

À l'aide de Google Cloud CLI ou de l'API Logging, vous pouvez ajouter des index personnalisés à des buckets de journaux existants ou nouveaux. Lorsque vous sélectionnez des champs supplémentaires à inclure dans l'index personnalisé, tenez compte des limites suivantes :

  • Vous pouvez ajouter jusqu'à 20 champs par index personnalisé.
  • Une fois que vous avez configuré ou mis à jour l'index personnalisé d'un bucket, vous devez attendre une heure pour que les modifications s'appliquent à vos requêtes. Cette latence garantit l'exactitude des résultats des requêtes et accepte les journaux écrits dans le passé.
  • Logging applique l'indexation personnalisée aux données stockées dans les buckets de journaux après la création ou la modification de l'index. Les modifications apportées aux index personnalisés ne s'appliquent pas aux journaux de manière rétroactive.

Avant de commencer

Avant de commencer à configurer un index personnalisé, procédez comme suit :

  • Vérifiez que vous utilisez la dernière version de la gcloud CLI. Pour en savoir plus, consultez la page Gérer les composants de Google Cloud CLI.

  • Vérifiez que vous disposez d'un rôle Identity and Access Management avec les autorisations suivantes :

    Pour en savoir plus sur ces rôles, consultez la page Contrôle des accès avec IAM.

Définir l'index personnalisé

Pour chaque champ que vous ajoutez à l'index personnalisé d'un bucket, vous définissez deux attributs : un chemin de champ et un type de champ :

  • fieldPath : décrit le chemin spécifique vers le LogEntry champ dans vos entrées de journal. Par exemple, jsonPayload.req_status.
  • type : indique si le champ est de type chaîne ou entier. Les valeurs possibles sont INDEX_TYPE_STRING et INDEX_TYPE_INTEGER.

Vous pouvez ajouter un index personnalisé en créant un bucket ou en mettant à jour un bucket existant. Pour en savoir plus sur la configuration des buckets, consultez la page Configurer les buckets de journaux.

Pour configurer un index personnalisé lors de la création d'un bucket, procédez comme suit :

gcloud

Utilisez la gcloud logging buckets create commande et définissez l'option --index :

gcloud logging buckets create BUCKET_NAME \
--location=LOCATION \
--description="DESCRIPTION" \
--index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

Exemple de commande :

gcloud logging buckets create int_index_test_bucket \
--location=global \
--description="Bucket with integer index" \
--index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

Pour créer un bucket, utilisez projects.locations.buckets.create dans l'API Logging. Préparez les arguments de la méthode comme suit :

  1. Définissez le param0/}ètre comme la ressource dans laquelle créer le bucket: projects/PROJECT_ID/locations/LOCATIONparent

    La variable LOCATION fait référence à la région dans laquelle vous souhaitez stocker vos journaux.

    Par exemple, si vous souhaitez créer un bucket pour le projet my-project dans la région asia-east2, votre paramètre parent se présentera comme suit : projects/my-project/locations/asia-east2.

  2. Définissez le paramètre bucketId (par exemple, my-bucket).

  3. Dans le corps de la requête LogBucket, configurez l'objet IndexConfig pour créer l'index personnalisé.

  4. Appelez projects.locations.buckets.create pour créer le bucket.

Pour mettre à jour un bucket existant afin d'y inclure un index personnalisé, procédez comme suit :

gcloud

Utilisez la gcloud logging buckets update commande et définissez l'option --add-index :

gcloud logging buckets update BUCKET_NAME \
--location=LOCATION \
--add-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

Exemple de commande :

gcloud logging buckets update int_index_test_bucket \
--location=global \
--add-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

Utilisez projects.locations.buckets.patch dans l'API Logging. Dans le LogBucket corps de la requête, configurez l'objet IndexConfig pour inclure les champs LogEntry que vous souhaitez indexer.

Supprimer un champ indexé personnalisé

Pour supprimer un champ de l'index personnalisé d'un bucket, procédez comme suit :

gcloud

Utilisez la gcloud logging buckets update commande et définissez l'option --remove-indexes :

gcloud logging buckets update BUCKET_NAME \
--location=LOCATION \
--remove-indexes=INDEX_FIELD_NAME

Exemple de commande :

gcloud logging buckets update int_index_test_bucket \
--location=global \
--remove-indexes=jsonPayload.req_status

API

Utilisez projects.locations.buckets.patch dans l'API Logging. Dans le corps de la requête LogBucket, supprimez les champs LogEntry de l'objet IndexConfig.

Mettre à jour le type de données du champ indexé personnalisé

Si vous devez corriger le type de données d'un champ indexé personnalisé, procédez comme suit :

gcloud

Utilisez la gcloud logging buckets update commande et définissez l'option --update-index :

gcloud logging buckets update BUCKET_NAME \
--location=LOCATION \
--update-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

Exemple de commande :

gcloud logging buckets update int_index_test_bucket \
--location=global \
--update-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

Utilisez projects.locations.buckets.patch dans l'API Logging. Dans le LogBucket corps de la requête, mettez à jour l'objet IndexConfig pour fournir le type de données correct pour un champ LogEntry.

Mettre à jour le chemin d'un champ indexé personnalisé

Si vous devez corriger le chemin d'un champ indexé personnalisé, procédez comme suit :

gcloud

Utilisez la gcloud logging buckets update commande et définissez les options --remove-indexes et --update-index :

gcloud logging buckets update BUCKET_NAME \
--location=LOCATION \
--remove-indexes=OLD_INDEX_FIELD_NAME \
--update-index=fieldPath=NEW_INDEX_FIELD_NAME,type=INDEX_TYPE

Exemple de commande :

gcloud logging buckets update int_index_test_bucket \
--location=global \
--remove-indexes=jsonPayload.req_status_old_path \
--add-index=fieldPath=jsonPayload.req_status_new_path,type=INDEX_TYPE_INTEGER

API

Utilisez projects.locations.buckets.patch dans l'API Logging. Dans le LogBucket corps de la requête, mettez à jour l' IndexConfig objet pour fournir le chemin de champ correct pour un LogEntry champ.

Répertorier tous les champs indexés pour un bucket

Pour répertorier les détails d'un bucket, y compris ses champs indexés personnalisés, procédez comme suit :

gcloud

Utilisez la gcloud logging buckets describe commande :

gcloud logging buckets describe BUCKET_NAME \
--location=LOCATION

Exemple de commande :

gcloud logging buckets describe indexed-bucket \
--location global

API

Utilisez projects.locations.buckets.get dans l'API Logging.

Effacer les champs indexés personnalisés

Pour supprimer tous les champs indexés personnalisés d'un bucket, procédez comme suit :

gcloud

Utilisez la gcloud logging buckets update commande et ajoutez l'option --clear-indexes :

gcloud logging buckets update BUCKET_NAME \
--location=LOCATION \
--clear-indexes

Exemple de commande :

gcloud logging buckets update int_index_test_bucket \
--location=global \
--clear-indexes

API

Utilisez projects.locations.buckets.patch dans l'API Logging. Dans le corps de la requête LogBucket, supprimez l'objet IndexConfig.

Interroger et afficher les données indexées

Pour interroger les données incluses dans les champs indexés personnalisés, limitez le champ d'application de votre requête au bucket qui contient les champs indexés personnalisés et spécifiez la vue de journal appropriée :

gcloud

Pour lire les journaux d'un bucket de journaux, utilisez la commande gcloud logging read et ajoutez un LOG_FILTER pour inclure vos données indexées :

gcloud logging read LOG_FILTER --bucket=BUCKET_ID --location=LOCATION --view=LOG_VIEW_ID

API

Pour lire les journaux d'un bucket de journaux, utilisez la entries.list méthode. Définissez resourceNames pour spécifier le bucket et la vue de journal appropriés, et définissez filter pour sélectionner vos données indexées.

Pour en savoir plus sur la syntaxe de filtrage, consultez la page Langage de requête Logging.

Indexation et types de champs

La façon dont vous configurez l'indexation des champs personnalisés peut avoir une incidence sur la façon dont les journaux sont stockés dans les buckets de journaux et sur la façon dont les requêtes sont traitées.

Au moment de l'écriture

Logging tente d'utiliser l'index personnalisé sur les données stockées dans les buckets de journaux après la création de l'index.

Les champs indexés sont typés, ce qui a des implications sur l'horodatage de l'entrée de journal. Lorsque l'entrée de journal est stockée dans le bucket de journaux, le champ de journal est évalué par rapport au type d'index à l'aide des règles suivantes :

  • Si le type d'un champ est identique à celui de l'index, les données sont ajoutées à l'index telles quelles.
  • Si le type du champ est différent de celui de l'index, Logging tente de le convertir par coercition dans le type de l'index (par exemple, d'entier à chaîne).
    • Si la conversion par coercition échoue, les données ne sont pas indexées. Si la conversion par coercition réussit, les données sont indexées.

Au moment de la requête

L'activation d'un index sur un champ modifie la façon dont vous devez interroger ce champ. Par défaut, Logging applique des contraintes de filtre aux champs en fonction du type de données de chaque entrée de journal en cours d'évaluation. Lorsque l'indexation est activée, les contraintes de filtre sur un champ sont appliquées en fonction du type d'index. L'ajout d'un index sur un champ impose un schéma à ce champ.

Lorsqu'un index personnalisé est configuré pour un bucket, les comportements de correspondance de schéma diffèrent lorsque ces deux conditions sont remplies :

  • Le type de données source d'un champ ne correspond pas au type d'index de ce champ.
  • L'utilisateur applique une contrainte à ce champ.

Prenons les charges utiles JSON suivantes :

{"jsonPayload": {"name": "A", "value": 12345}}
{"jsonPayload": {"name": "B", "value": "3"}}

Appliquez maintenant ce filtre à chacune d'elles :

jsonPayload.value > 20

Si le champ jsonPayoad.value ne dispose pas d'indexation personnalisée, Logging applique une correspondance de type flexible :

  • Pour "A", Logging observe que la valeur de la clé "value" est en fait un entier et que la contrainte "20" peut être convertie en entier. Logging évalue ensuite 12345 > 20 et renvoie "true" (vrai) car c'est le cas numériquement.

  • Pour "B", Logging observe que la valeur de la clé "value" est en fait une chaîne. Il évalue ensuite "3" > "20" et renvoie "true", car c'est le cas de manière alphanumérique.

Si le champ jsonPayload.value est inclus dans l'index personnalisé, Logging évalue cette contrainte à l'aide de l'index au lieu de la logique Logging habituelle. Le comportement change :

  • Si l'index est de type chaîne, toutes les comparaisons sont des comparaisons de chaînes.
    • L'entrée "A" ne correspond pas, car "12345" n'est pas supérieur à "20" de manière alphanumérique. L'entrée "B" correspond, car la chaîne "3" est supérieure à "20".
  • Si l'index est de type entier, toutes les comparaisons sont des comparaisons d'entiers.
    • L'entrée "B" ne correspond pas, car "3" n'est pas supérieur à "20" de manière numérique. L'entrée "A" correspond, car "12345" est supérieur à "20".

Cette différence de comportement est subtile et doit être prise en compte lors de la définition et de l'utilisation d'index personnalisés.

Cas particulier de filtrage

Pour l'index de type entier jsonPayload.value, supposons qu'une valeur de chaîne soit filtrée :

jsonPayload.value = "hello"

Si la valeur de la requête ne peut pas être convertie par coercition dans le type d'index, l'index est ignoré.

Toutefois, supposons que pour un index de type chaîne, vous transmettez une valeur entière :

jsonPayload.value > 50

Ni A ni B ne correspondent, car ni "12345" ni "3" ne sont supérieurs à "50" de manière alphanumérique.