Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Enregistrez et réexécutez les requêtes CloudWatch Logs Insights

Après avoir créé une requête, vous pouvez l'enregistrer et la réexécuter ultérieurement. Les requêtes sont enregistrées dans une structure de dossiers afin que vous puissiez les organiser. Vous pouvez enregistrer jusqu'à 1 000 requêtes par région et par compte.

Les requêtes sont enregistrées à un niveau spécifique à la région, et non à un niveau spécifique à l'utilisateur. Si vous créez et enregistrez une requête, les autres utilisateurs ayant accès aux CloudWatch journaux de la même région peuvent voir toutes les requêtes enregistrées et leurs structures de dossiers dans la région.

Pour enregistrer une requête, vous devez être connecté à un rôle disposant de l'autorisation logs:PutQueryDefinition. Pour afficher une liste des requêtes enregistrées, vous devez être connecté à un rôle disposant de l'autorisation logs:DescribeQueryDefinitions.

Console

Pour enregistrer une requête

1. Ouvrez la CloudWatch console à l'adresse https://console.aws.amazon.com/cloudwatch/.

2. Dans le panneau de navigation, choisissez Logs (Journaux), puis Logs Insights.

3. Dans l'éditeur de requête, créez une requête.

4. Choisissez Enregistrer.

5. Entrez un nom pour la requête.

6. (Facultatif) Choisissez un dossier dans lequel vous souhaitez enregistrer cette requête. Sélectionnez (Nouveau) pour créer un dossier. Si vous créez un dossier, vous pouvez utiliser des barres obliques (/) dans son nom pour définir une structure de dossier. Par exemple, le nom d'un nouveau dossier folder-level-1/folder-level-2 crée un dossier de niveau supérieur appelé folder-level-1, avec un autre dossier appelé folder-level-2 au sein de ce dossier. La requête est enregistrée dans folder-level-2.

7. (Facultatif) Modifiez les groupes de journaux ou le texte de la requête.

8. (Facultatif) Pour utiliser des paramètres dans votre requête, procédez comme suit :

   1. Ajoutez des paramètres à votre requête. Remplacez les valeurs statiques par des espaces réservés en utilisant la {{parameter}} syntaxe (doubles accolades avant et après le nom du paramètre).

      Exemple : requête originale avec des valeurs statiques :

      fields @timestamp, @message
      | filter level = "Error"
      | filter applicationName = "OrderService"

      Requête mise à jour avec paramètres :

      fields @timestamp, @message
      | filter level = {{logLevel}}
      | filter applicationName = {{applicationName}}

   2. Définissez les paramètres utilisés dans votre requête. Pour chaque paramètre d'espace réservé, spécifiez :

      • Nom : doit correspondre exactement au nom de l'espace réservé (par exemple,logLevel,applicationName).

      • Valeur par défaut (facultatif) : valeur à utiliser si aucune valeur de paramètre n'est fournie.

      • Description (facultatif) : explique l'objectif du paramètre.

   3. Les requêtes avec paramètres peuvent être exécutées en utilisant le nom de la requête avec un $ préfixe et en transmettant les noms des paramètres sous forme de paires clé-valeur. Pour plus de détails, reportez-vous à la section Pour exécuter une requête enregistrée.

9. Choisissez Enregistrer.

AWS CLI

Pour enregistrer une requête, utilisez put-query-definition :

aws logs put-query-definition \
  --name "ErrorsByLevel" \
  --query-string "fields @timestamp, @message | filter level = \"ERROR\"" \
  --log-group-names "/aws/lambda/my-function" \
  --region us-east-1

(Facultatif) Pour enregistrer une requête avec des paramètres, ajoutez l'--parametersoption et utilisez des {{parameterName}} espaces réservés dans la chaîne de requête :

aws logs put-query-definition \
  --name "ErrorsByLevel" \
  --query-string "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}" \
  --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"},{"name":"applicationName","defaultValue":"OrderService","description":"Application name to filter"}]' \
  --log-group-names "/aws/lambda/my-function" \
  --region us-east-1

Pour enregistrer une requête dans un dossier, préfixez le nom de la requête par le chemin du dossier :

aws logs put-query-definition \
  --name "my-folder/ErrorsByLevel" \
  --query-string "fields @timestamp, @message | filter level = {{logLevel}}" \
  --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"}]' \
  --log-group-names "/aws/lambda/my-function" \
  --region us-east-1

API

Pour enregistrer une requête, appelez PutQueryDefinition:

{
  "name": "ErrorsByLevel",
  "queryString": "fields @timestamp, @message | filter level = \"ERROR\"",
  "logGroupNames": ["/aws/lambda/my-function"]
}

(Facultatif) Pour enregistrer une requête avec des paramètres, incluez le parameters champ et utilisez des {{parameterName}} espaces réservés dans la chaîne de requête :

{
  "name": "ErrorsByLevel",
  "queryString": "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}",
  "logGroupNames": ["/aws/lambda/my-function"],
  "parameters": [
    {
      "name": "logLevel",
      "defaultValue": "ERROR",
      "description": "Log level to filter"
    },
    {
      "name": "applicationName",
      "defaultValue": "OrderService",
      "description": "Application name to filter"
    }
  ]
}

Console

Pour exécuter une requête enregistrée

1. Ouvrez la CloudWatch console à l'adresse https://console.aws.amazon.com/cloudwatch/.

2. Dans le panneau de navigation, choisissez Logs (Journaux), puis Logs Insights.

3. Sur la droite, choisissez Queries (Requêtes).

4. Sélectionnez votre requête dans la liste des requêtes enregistrées. Le texte de la requête apparaît dans l'éditeur de requêtes.

5. (Facultatif) Pour utiliser une requête paramétrée :

   1. Cliquez sur l'icône + à côté du nom de la requête dans le panneau latéral des requêtes enregistrées.

   2. La requête paramétrée apparaît dans l'éditeur de requêtes. Par exemple, si vous choisissez l'icône + à côtéErrorsByLevel, l'éditeur de requêtes est renseigné avec : $ErrorsByLevel(level=, applicationName=)

   3. Fournissez les valeurs des paramètres (level, ApplicationName) et exécutez la requête. Par exemple : $ErrorsByLevel(level= "ERROR", applicationName= "OrderService")

6. Cliquez sur Exécuter.

AWS CLI

Pour exécuter une requête enregistrée avec des paramètres

À utiliser start-query avec la $QueryName() syntaxe suivante :

aws logs start-query \
  --log-group-names "/aws/lambda/my-function" \
  --start-time 1707566400 --end-time 1707570000 \
  --query-string '$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")' \
  --region us-east-1

API

Pour exécuter une requête enregistrée avec des paramètres

Appelez StartQueryavec la $QueryName() syntaxe dans le queryString champ :

{
  "logGroupNames": ["/aws/lambda/my-function"],
  "startTime": 1707566400,
  "endTime": 1707570000,
  "queryString": "$ErrorsByLevel(level=\"ERROR\", applicationName= \"OrderService\")"
}

Pour supprimer une requête, vous devez être connecté à un rôle disposant de l'autorisation logs:DeleteQueryDefinition.

Utilisation de requêtes enregistrées avec paramètres

Les requêtes enregistrées avec paramètres sont des modèles de requêtes réutilisables avec des espaces réservés nommés. Au lieu de conserver plusieurs copies de requêtes presque identiques, vous pouvez enregistrer un modèle et fournir différentes valeurs de paramètres lors de l'exécution de la requête. Les paramètres ne sont pris en charge que dans le langage de requête CloudWatch Logs Insights.

Fonctionnement

Lorsque vous enregistrez une requête, les espaces réservés identifient les valeurs que vous pouvez fournir au moment de l'exécution de la requête. Les espaces réservés utilisent la {{parameterName}} syntaxe. Voici un exemple de requête enregistrée nommée ErrorsByLevel avec deux paramètres logLevel etapplicationName.

fields @timestamp, @message
| filter level = {{logLevel}}
| filter applicationName = {{applicationName}}

Pour exécuter une requête enregistrée, vous pouvez l'invoquer en utilisant le nom de la requête préfixé par $ et en transmettant les valeurs des paramètres. Le moteur de requête CloudWatch Logs Insights remplace chaque espace réservé. Si un paramètre contient des valeurs par défaut, ces valeurs sont utilisées si aucune autre valeur n'est fournie.

# Run query by using query name and passing parameter values explicitly
$ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService")

# Run query without specifying parameter values - default values are used in this case.
$ErrorsByLevel()

Les noms de requêtes enregistrés contenant des espaces ou des caractères spéciaux doivent être suivis de backticks :

$`Errors By Level`(logLevel = "WARN")

Exemples de requêtes enregistrées avec paramètres

Ajouter une limite de résultats en tant que paramètre

Nom de la requête : ErrorsByLevel avec paramètres logLevel (par défaut :"ERROR"), applicationName (par défaut :"OrderService") et maxResults (par défaut :50)

fields @timestamp, @message, @logStream
| filter level = {{logLevel}}
| filter applicationName = {{applicationName}}
| sort @timestamp desc
| limit {{maxResults}}

# Run the query using the query name and passing parameter values
$ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService", maxResults = 100)

Utilisation de plusieurs requêtes enregistrées avec paramètres

L'exemple ci-dessous utilise ErrorsByLevel une seconde requête RecentN enregistrée définie comme sort @timestamp desc | limit {{count}} (avec paramètrecount, par défaut20). Le moteur de requêtes CloudWatch Logs Insights développe chaque requête avant de l'exécuter.

# Using multiple queries with parameters in sequence
$ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService")
| $RecentN(count = 10)

# Each of the queries is expanded, resulting in the following query when it is run.
fields @timestamp, @message
| filter level = "WARN"
| filter applicationName = "OrderService"
| sort @timestamp desc
| limit 10

Quotas et gestion des erreurs

La chaîne de requête étendue ne peut pas dépasser 10 000 caractères. Les noms des paramètres doivent commencer par une lettre ou un trait de soulignement. Une requête enregistrée ne peut pas faire référence à une autre requête enregistrée (les invocations imbriquées ne sont pas prises en charge).