Ce document explique comment ajouter des champs LogEntry indexés à vos buckets Cloud Logging pour accélérer l'interrogation des données de vos journaux.
Présentation
Les performances des requêtes sont essentielles à toute solution de journalisation. À mesure que les charges de travail s'adaptent le volume de journaux correspondant augmente, l'indexation de vos données de journaux les plus utilisées réduire la durée des requêtes.
Pour améliorer les performances des requêtes, Logging indexe automatiquement les champs LogEntry suivants:
- resource.type
- resource.labels.*
- logName
- severity
- timestamp
- insertId
- operation.id
- trace
- httpRequest.status
- labels.*
- split.uid
En plus des champs que Logging indexe automatiquement, vous pouvez également demander à un bucket de journaux d'indexer d'autres champs LogEntry en créant un indice personnalisé pour le bucket.
Par exemple, supposons 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 font référence
jsonPayload.request.status
si l'expression de requête inclut ce champ.
À l'aide de la 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é, notez les limites suivantes:
- Vous pouvez ajouter jusqu'à 20 champs par index personnalisé.
- Après avoir configuré ou mis à jour l'index personnalisé d'un bucket, vous devez attendre pendant une heure pour que les modifications s'appliquent à vos requêtes. Cette latence garantit l'exactitude des résultats de la requête et accepte les journaux écrits dans le passé.
- Logging applique une indexation personnalisée aux données stockées des buckets de journaux après la création ou la modification de l'index ; modifications apportées aux paramètres personnalisés les index 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 du gcloud CLI. Pour en savoir plus, consultez Gérer les composants de la Google Cloud CLI
Vérifiez que vous disposez d'un rôle Identity and Access Management doté des autorisations suivantes:
Pour en savoir plus sur ces rôles, consultez la section 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 Attributs: chemin d'accès et type de champ:
fieldPath
: décrit le chemin d'accès spécifique au champ LogEntry dans votre les entrées de journal correspondantes. Par exemple,jsonPayload.req_status
.type
: indique si le champ est de type chaîne ou entier. La les valeurs possibles sontINDEX_TYPE_STRING
etINDEX_TYPE_INTEGER
.
Vous pouvez ajouter un index personnalisé en créant un bucket ou en 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 le
gcloud logging buckets create
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 le l'API Logging. Préparez les arguments de la méthode comme suit :
Définissez le paramètre
parent
comme étant la ressource dans laquelle pour créer le bucket:projects/PROJECT_ID/locations/LOCATION
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 dans la régionasia-east2
, votre paramètreparent
se présente comme suit : ceci:projects/my-project/locations/asia-east2
Définissez le paramètre
bucketId
. Exemple :my-bucket
.Dans le corps de la requête
LogBucket
, configurez l'objet IndexConfig. pour créer l'index personnalisé.Appelez projects.locations.buckets.create pour créer le bucket.
Pour mettre à jour un bucket existant afin d'inclure un index personnalisé, procédez comme suit:
gcloud
Utilisez le
gcloud logging buckets update
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 corps de la requête LogBucket, 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 le
gcloud logging buckets update
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 LogBucket, supprimez les champs LogEntry du IndexConfig.
Modifier 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 le
gcloud logging buckets update
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 LogBucket, mettez à jour l'objet IndexConfig pour fournir le type de données correct pour un champ LogEntry.
Modifier le chemin d'un champ indexé personnalisé
Si vous devez corriger le chemin d'accès d'un champ indexé personnalisé, procédez comme suit:
gcloud
Utilisez le
gcloud logging buckets update
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 LogBucket, mettez à jour l'objet IndexConfig pour fournir le chemin d'accès correct pour un champ LogEntry.
Répertorier tous les champs indexés d'un bucket
Pour répertorier les détails d'un bucket, y compris ses champs indexés personnalisés, exécutez la commande suivante : suivantes:
gcloud
Exécutez la commande gcloud logging buckets describe
:
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 les
gcloud logging buckets update
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 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 la portée de votre au bucket contenant 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 classe
gcloud logging read et d'ajouter une
LOG_FILTER
à inclure
vos données indexées:
gcloud logging read LOG_FILTER --bucket=BUCKET_ID --location=LOCATION --view=VIEW_ID
API
Pour lire les journaux d'un bucket de journaux, utilisez la classe
entries.list
. Définissez resourceNames
pour spécifier le bucket et la vue de journal appropriés, puis 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 manière dont vous configurez l'indexation des champs personnalisés peut avoir une incidence sur le stockage des journaux dans les buckets de journaux et le traitement des requêtes.
Au moment de l'écriture
Logging tente d'utiliser l'index personnalisé sur les données stockés dans des buckets de journaux après la création de l'index.
Les champs indexés sont saisis par type, ce qui a des conséquences sur l'horodatage 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 mot pour mot.
- Si le type du champ est différent de celui de l'index, alors
Logging tente de le convertir par coercition dans le type d'index (par
(exemple, entier en chaîne).
- Si la coercition de type échoue, les données ne sont pas indexées. Lorsque vous saisissez la coercition réussit, les données sont indexées.
Au moment de la requête
L'activation d'un indice sur un champ modifie la façon dont vous devez interroger ce champ. Par défaut, la journalisation applique des contraintes de filtrage aux champs en fonction du type de données de chaque entrée de journal évaluée. Quand l'indexation est activée, les contraintes de filtre d'un champ sont appliquées en fonction du type de l'index. L'ajout d'un index sur un champ impose un schéma à ce champ.
Lorsqu'un indice personnalisé est configuré pour un bucket, les comportements de mise en correspondance de schémas diffèrent lorsque les deux conditions suivantes 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 l'exemple des charges utiles JSON suivantes:
{"jsonPayload": {"name": "A", "value": 12345}} {"jsonPayload": {"name": "B", "value": "3"}}
Appliquez maintenant ce filtre à chacun d'eux:
jsonPayload.value > 20
Si le champ jsonPayoad.value
ne comporte pas d'indexation personnalisée, alors
Logging applique une correspondance de type flexible:
Pour "A", Logging observe que la valeur de "value" est en fait un entier, et que la contrainte "20" peut être convertie en entier. Logging évalue ensuite
12345 > 20
et renvoie "vrai" car c'est le cas numérique.Pour "B", Logging observe que la valeur de la "valeur" touche est en fait une chaîne. Elle évalue ensuite
"3" > "20"
et renvoie "true", puisque c'est le cas qui se compose de caractères alphanumériques.
Si le champ jsonPayload.value
est inclus dans l'index personnalisé, alors
Logging évalue cette contrainte à l'aide de l'index au lieu de la
la logique de journalisation habituelle. Le comportement change:
- Si l'index est de type chaîne, toutes les comparaisons sont des comparaisons de chaînes.
- Le "A" l'entrée ne correspond pas, car "12345" n'est pas supérieur à "20" alphanumérique. Le "B" l'entrée correspond, puisque la chaîne "3" est supérieur à à "20".
- Si l'index est de type entier, toutes les comparaisons sont des comparaisons d'entiers.
- Le "B" l'entrée ne correspond pas, car "3" n'est pas supérieur à "20" numériquement. La valeur "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 à l'aide d'index personnalisés.
Filtrer les cas spéciaux
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 en type d'index, l'index est ignoré.
Cependant, supposons que vous transmettiez une valeur entière pour un index de type chaîne:
jsonPayload.value > 50
Ni A, ni B ne correspondent (ni "12345") ni "3" est alphanumérique supérieur à "50".