Configurer l'indexation personnalisée

Ce document explique comment ajouter des champs LogEntry indexés à vos buckets Cloud Logging pour accélérer les requêtes sur vos données de journaux.

Présentation

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

Pour améliorer les performances des requêtes, la journalisation 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 index personnalisé pour le bucket.

Par exemple, supposons que vos expressions de requête incluent souvent le champ jsonPayload.request.status. Vous pouvez configurer un indice personnalisé pour un bucket qui inclut jsonPayload.request.status. Toute requête ultérieure sur les données de ce bucket renverra les données jsonPayload.request.status indexées 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é, tenez compte des restrictions suivantes:

• Vous pouvez ajouter jusqu'à 20 champs par indice 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 soient appliquées à vos requêtes. Cette latence garantit l'exactitude des résultats de la requête et accepte les journaux écrits par le passé.
• La journalisation applique l'indexation personnalisée aux données stockées dans des 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 rétroactivement aux journaux.

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 IAM (Identity and Access Management) doté des autorisations suivantes:

  • roles/logging.admin
  • roles/logging.configWriter

  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 devez définir deux attributs: un chemin d'accès de champ et un type de champ:

• fieldPath: décrit le chemin d'accès spécifique au champ LogEntry 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 indice personnalisé en créant un bucket ou en mettant à jour un bucket existant. Pour en savoir plus sur la configuration des buckets, consultez la section Configurer les buckets de journaux.

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

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

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

Pour mettre à jour un bucket existant afin qu'il inclue un indice personnalisé, procédez comme suit:

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

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

Supprimer un champ indexé personnalisé

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

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

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

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 logging buckets update BUCKET_NAME\
--location=LOCATION\
--update-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

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

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 logging buckets update BUCKET_NAME\
--location=LOCATION\
--remove-indexes=OLD_INDEX_FIELD_NAME \
--update-index=fieldPath=NEW_INDEX_FIELD_NAME,type=INDEX_TYPE

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

Lister tous les champs indexés d'un bucket

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

gcloud logging buckets describe BUCKET_NAME\
--location=LOCATION

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

Effacer les champs indexés personnalisés

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

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

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

Interroger et afficher des données indexées

Pour interroger les données incluses dans des champs indexés personnalisés, limitez la portée de votre requête au bucket contenant les champs indexés personnalisés et spécifiez la vue de journal appropriée:

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

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 un impact 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

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

Les champs indexés sont typés, ce qui a des conséquences sur le code temporel 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, la journalisation tente de le convertir en type d'index (par exemple, en convertissant un entier en chaîne).
  • Si la coercition de type échoue, les données ne sont pas indexées. Lorsque la coercition de type aboutit, 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. Lorsque l'indexation est activée, les contraintes de filtre sur un champ sont appliquées en fonction du type de l'index. L'ajout d'un indice à 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 les charges utiles JSON suivantes:

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

Appliquez maintenant ce filtre à chacun des éléments suivants:

jsonPayload.value > 20

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

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

• Pour "B", la journalisation constate 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 alphanumériquement.

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 de journalisation habituelle. Le comportement change:

• Si l'index est de type chaîne, toutes les comparaisons sont des comparaisons de chaînes.
  • La valeur "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.
  • La valeur "B" ne correspond pas, car "3" n'est pas numériquement supérieur à "20". La réponse "A" est correcte, 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 de filtrage de bord

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é.

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

jsonPayload.value > 50

Ni A ni B ne correspondent, car ni "12345" ni "3" ne sont alphanumériquement supérieurs à "50".