OpenSearch Langage de requête structuré (SQL) - Amazon CloudWatch Logs
Commandes SQL prises en chargeSQL pris en charge pour les multi-log-group requêtesSQL pris en charge pour les requêtes de source de donnéesÉtendue de la requêteRestrictions

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.

OpenSearch Langage de requête structuré (SQL)

Cette section contient une introduction de base à l'interrogation des CloudWatch journaux à l'aide de OpenSearch SQL. Il s'agit d'une option familière si vous avez l'habitude de travailler avec des bases de données relationnelles. OpenSearch SQL offre un sous-ensemble de fonctionnalités SQL, ce qui en fait un bon choix pour effectuer des requêtes ad hoc et des tâches d'analyse de données. Avec OpenSearch SQL, vous pouvez utiliser des commandes telles que SELECT, FROM, WHERE, GROUP BY, HAVING et diverses autres commandes et fonctions SQL. Vous pouvez exécuter des tâches JOINs dans différents groupes de journaux, corréler les données entre les groupes de journaux à l'aide de sous-requêtes et utiliser le riche ensemble de fonctions JSON, mathématiques, de chaîne, conditionnelles et autres fonctions SQL pour effectuer une analyse approfondie des données de journal et de sécurité.

filterIndexÀ utiliser pour renvoyer uniquement des données indexées, en forçant une requête à analyser uniquement les groupes de journaux indexés sur un champ que vous spécifiez dans la requête. Réduisez le volume numérisé en ignorant les groupes de journaux qui ne contiennent aucun événement de journal contenant le champ spécifié dans la requête, et en analysant uniquement les groupes de journaux correspondant à la valeur spécifiée dans la requête pour cet index de champ. filterIndexÀ utiliser pour spécifier le nom du champ, ainsi que le nom et la valeur du champ pour interroger uniquement les données indexées contenant le champ et la valeur spécifiés.

Vous pouvez utiliser le OpenSearch SQL pour les requêtes de groupes de journaux dans la classe de journal standard. SQL prend également en charge les requêtes à l'aide du nom et du type de source de données.

Note

Le tableau suivant répertorie les commandes et fonctions SQL prises en charge dans les CloudWatch journaux. Pour plus d'informations sur toutes les commandes OpenSearch SQL, y compris la syntaxe, consultez la section Commandes SQL prises en charge dans le Guide du développeur de OpenSearch services.

Pour plus d'informations sur les autres langages de requête que vous pouvez utiliser, consultez CloudWatch Logs Insights, OpenSearch Service PPL et CloudWatch Metrics Insights.

Commandes SQL prises en charge

Note

Dans la colonne d'exemple de requête, remplacez le cas <logGroup> échéant en fonction de la source de données que vous interrogez.

Commande ou fonction Exemple de requête Description

SELECT

SELECT `@message`, Operation FROM `LogGroupA`

Affiche les valeurs projetées.

FROM

SELECT `@message`, Operation FROM `LogGroupA`

Clause intégrée qui spécifie les tables ou les vues sources à partir desquelles récupérer les données, prenant en charge différents types de jointures et de sous-requêtes.

WHERE

SELECT * FROM `LogGroupA` WHERE Operation = 'x'

Les filtres enregistrent les événements en fonction des critères de champ fournis.

Index des filtres

SELECT * FROM `filterIndex('region' = 'us-east-1')` WHERE status = 200 LIMIT 10;

Renvoie uniquement les données indexées, en forçant une requête à analyser uniquement les groupes de journaux indexés sur un champ que vous spécifiez dans la requête.

GROUP BY

SELECT `@logStream`, COUNT(*) as log_count FROM `LogGroupA` GROUP BY `@logStream`

Les groupes enregistrent les événements par catégorie et trouvent la moyenne en fonction des statistiques.

HAVING

SELECT `@logStream`, COUNT(*) as log_count FROM `LogGroupA` GROUP BY `@logStream` HAVING log_count > 100

Filtre les résultats en fonction des conditions de regroupement.

ORDER BY

SELECT * FROM `LogGroupA` ORDER BY `@timestamp` DESC

Classe les résultats en fonction des champs de la clause ORDER BY. Vous pouvez trier par ordre décroissant ou croissant.

JOIN

SELECT A.`@message`, B.`@timestamp`FROM `LogGroupA` as A INNER JOIN `LogGroupB` as B ON A.`requestId` = B.`requestId`

Joint les résultats de deux tables en fonction de champs communs. La jointure interne ou la jointure externe gauche doivent être spécifiées

LIMIT

Select * from `LogGroupA` limit 10

Limite les résultats de requête affichés aux N premières lignes.

Fonctions de chaîne

SELECT upper(Operation) , lower(Operation), Operation FROM `LogGroupA`

Fonctions intégrées dans SQL permettant de manipuler et de transformer des chaînes de caractères et des données textuelles dans des requêtes SQL. Par exemple, convertir des majuscules, combiner des chaînes, extraire des parties et nettoyer du texte.

Fonctions de date

SELECT current_date() as today, date_add(current_date(), 30) as thirty_days_later, last_day(current_date()) as month_end FROM `LogGroupA`

Fonctions intégrées pour gérer et transformer les données de date et d'horodatage dans les requêtes SQL. Par exemple, date_add, date_format, datediff et current_date.

Fonctions conditionnelles

SELECT Operation, IF(Error > 0, 'High', 'Low') as error_category FROM `LogGroupA`;

Fonctions intégrées qui exécutent des actions en fonction de conditions spécifiées ou qui évaluent les expressions de manière conditionnelle. Par exemple, CASE et IF.

Fonctions d’agrégation

SELECT AVG(bytes) as bytesWritten FROM `LogGroupA`

Fonctions intégrées qui effectuent des calculs sur plusieurs lignes pour produire une seule valeur résumée. Par exemple, SUM, COUNT, AVG, MAX et MIN.

Fonctions JSON

SELECT get_json_object(json_column, '$.name') as name FROM `LogGroupA`

Fonctions intégrées pour analyser, extraire, modifier et interroger des données au format JSON dans des requêtes SQL (par exemple, from_json, to_json, get_json_object, json_tuple) permettant de manipuler les structures JSON dans les ensembles de données.

Fonctions de tableau

SELECT scores, size(scores) as length, array_contains(scores, 90) as has_90 FROM `LogGroupA`;

Fonctions intégrées permettant de travailler avec des colonnes de type tableau dans les requêtes SQL, permettant des opérations telles que l'accès, la modification et l'analyse de données de tableau (par exemple, size, explode, array_contains).

Fonctions de fenêtrage

SELECT field1, field2, RANK() OVER (ORDER BY field2 DESC) as field2Rank FROM `LogGroupA`;

Fonctions intégrées qui effectuent des calculs sur un ensemble spécifique de lignes liées à la ligne actuelle (fenêtre), permettant des opérations telles que le classement, les totaux cumulés et les moyennes mobiles. Par exemple, ROW_NUMBER, RANK, LAG et LEAD

Fonctions de conversion

SELECT CAST('123' AS INT) as converted_number, CAST(123 AS STRING) as converted_string FROM `LogGroupA`

Fonctions intégrées pour convertir les données d'un type à un autre dans les requêtes SQL, permettant des transformations de type de données et des conversions de format. Par exemple, CAST, TO_DATE, TO_TIMESTAMP et BINARY.

Fonctions de prédicat

SELECT scores, size(scores) as length, array_contains(scores, 90) as has_90 FROM `LogGroupA`;

Fonctions intégrées qui évaluent les conditions et renvoient des valeurs booléennes (vrai/faux) en fonction de critères ou de modèles spécifiés. Par exemple, IN, LIKE, BETWEEN, IS NULL et EXISTS.

Sélectionnez plusieurs groupes de journaux

SELECT lg1.field1, lg1.field2 from `logGroups( logGroupIdentifier: ['LogGroup1', 'LogGroup2'])` as lg1 where lg1.field3= "Success"

Vous permet de spécifier plusieurs groupes de journaux dans une instruction SELECT

Sélectionnez plusieurs sources de données

SELECT ds1.field1, ds1.field2 from `dataSource(['DataSource1', 'DataSource2'])` as ds1 where ds1.field3= "Success"

Vous permet de spécifier plusieurs sources de données dans une instruction SELECT

SQL pris en charge pour les multi-log-group requêtes

Pour faciliter l'interrogation de plusieurs groupes de journaux dans SQL, vous pouvez utiliser la logGroups commande. À l'aide de cette syntaxe, vous pouvez interroger plusieurs groupes de journaux en les spécifiant dans la commande FROM.

Syntaxe :

`logGroups(
    logGroupIdentifier: ['LogGroup1','LogGroup2', ...'LogGroupn']
)

Dans cette syntaxe, vous pouvez spécifier jusqu'à 50 groupes de journaux dans le logGroupIdentifier paramètre. Pour référencer des groupes de journaux dans un compte de surveillance, utilisez ARNs plutôt que des LogGroup noms.

Exemple de requête :

SELECT LG1.Column1, LG1.Column2 from `logGroups(
    logGroupIdentifier: ['LogGroup1', 'LogGroup2']
)` as LG1 WHERE LG1.Column1 = 'ABC'

La syntaxe suivante impliquant plusieurs groupes de journaux après l'FROMinstruction n'est PAS prise en charge lors de l'interrogation CloudWatch des journaux.

SELECT Column1, Column2 FROM 'LogGroup1', 'LogGroup2', ...'LogGroupn'
WHERE Column1 = 'ABC'

SQL pris en charge pour les requêtes de source de données

Pour faciliter l'utilisation des requêtes de sources de données dans SQL, vous pouvez utiliser la commande DataSource. À l'aide de cette syntaxe, vous pouvez interroger des sources de données en les spécifiant dans la FROM commande. Vous pouvez spécifier jusqu'à 10 sources de données.

Syntaxe

`dataSource(
    ['DataSource1', 'DataSource2', ...'DataSourcen']
)`

Exemple de requête

SELECT DS1.Column1, DS1.Column2 from `dataSource(
    ['DataSource1', 'DataSource2']
)` as DS1 WHERE DS1.Column1 = 'ABC'

Étendue de la requête

Dans l'API AWS CLI and, vous pouvez spécifier les journaux à interroger en utilisant le groupe de journaux, la source et le type de données, ainsi que les index des champs.

Groupe de journaux

La sélection de la source du groupe de journaux peut être utilisée lorsque les clients savent exactement quel ou quels groupes de journaux doivent être recherchés

SELECT * FROM `logGroups(logGroupIdentifier: ['/aws/lambda/my-function'])`;

Source et type de données

Les clients peuvent interroger leurs journaux en utilisant le nom et le type de source de données.

La sélection basée sur la source de données et le type de source peut être utilisée lorsque les clients savent quelles sources de données exactes doivent être interrogées. Cette requête est exécutée sur un ou plusieurs groupes de journaux contenant la source de données et le type spécifiés.

Pour faciliter l'utilisation des requêtes de sources de données dans SQL, vous pouvez utiliser la commande DataSource. À l'aide de cette syntaxe, vous pouvez interroger des sources de données en les spécifiant dans la commande FROM. Vous pouvez spécifier jusqu'à 10 sources de données.

Syntaxe :

`dataSource(
    ['DataSource1.Type1', 'DataSource2.Type2', ...'DataSourcen.Typen']
)`

Exemple de requête :

SELECT DS1.Column1, DS1.Column2 from `dataSource(
    ['DataSource1.Type1', 'DataSource2.Type2']
)` as DS1 WHERE DS1.Column1 = 'ABC'

Pour plus d'informations sur les requêtes par sources de données, consultezUtilisez des facettes pour regrouper et explorer les journaux.

Exemple combiné

Les clients peuvent spécifier tous les opérateurs de sélection de source dans les backticks dans n'importe quel ordre et les résultats seront basés sur l'intersection de toutes les conditions appliquées.

Par exemple,/aws/lambda/my-function-1 peut contenir plusieurs sources et types de données, y compris une grande variété d'index. Lorsque la requête suivante a été exécutée, les résultats renvoyés ne comporteront que des événements de source et de type DataSource 1.Type1 répondant aux critères « status » = 200.

SELECT * FROM `
   logGroups(logGroupIdentifier: ['/aws/lambda/my-function'])
   filterIndex('status' = 200)
   dataSource(['DataSource1.Type1'])
`;

Index des champs

La sélection de source basée sur l'index des champs identifie automatiquement les groupes de journaux pertinents lorsque vos filtres ciblent les champs indexés, réduisant ainsi le volume de numérisation et le temps d'exécution des requêtes.

filterIndexÀ utiliser pour renvoyer uniquement des données indexées, en forçant une requête à analyser uniquement les groupes de journaux indexés sur un champ que vous spécifiez dans la requête. Pour les groupes de journaux indexés sur ce champ, cela optimise davantage la requête en ignorant les groupes de journaux qui ne contiennent aucun événement de journal contenant le champ spécifié dans la requête pour le champ indexé. Il réduit encore le volume numérisé en essayant de scanner uniquement les événements de journal de ces groupes de journaux qui correspondent à la valeur spécifiée dans la requête pour cet index de champ. Pour plus d'informations sur les index de champs et sur la façon de les créer, voir Création d'index de champs pour améliorer les performances des requêtes et réduire le volume de numérisation.

En SQL, FilterIndex est utilisé pour spécifier quelles paires clé-valeur doivent être traitées comme des index. La syntaxe est la suivante

SELECT * FROM `filterIndex('region' = 'us-east-1')`;

Où :

  1. FilterIndex (...) indique de traiter les valeurs clés qu'elles contiennent comme des index de champs. Chaque paire clé-valeur est séparée par une virgule (exemple ci-dessous)

  2. 'region' = 'us-east-1' indique la condition réelle à appliquer

    1. Remarque : Au lieu de =, les clients peuvent utiliser IN pour spécifier plusieurs valeurs (exemple ci-dessous)

L'utilisation de plusieurs FilterIndex combinerait les conditions en utilisant « AND ». Dans l'exemple, les journaux correspondant à status=200 et à la région dans us-east-1 ou us-west-2 seraient interrogés.

SELECT * FROM `filterIndex('status' = 200, 'region' IN ['us-east-1', 'us-west-2'])`;

Restrictions

Les restrictions suivantes s'appliquent lorsque vous utilisez OpenSearch SQL pour effectuer des requêtes dans CloudWatch Logs Insights.

  • Vous ne pouvez inclure qu'un seul JOIN dans une instruction SELECT.

  • Vous ne pouvez pas utiliser JOIN ou des sous-requêtes avec des requêtes de source de données.

  • Un seul niveau de sous-requêtes imbriquées est pris en charge.

  • Les requêtes d'instruction multiples séparées par des points-virgules (;) ne sont pas prises en charge.

  • Les requêtes contenant des noms de champs identiques mais ne différant que dans certains cas (tels que field1 et FIELD1) ne sont pas prises en charge.

    Par exemple, la requête suivante n'est pas prise en charge :

    Select AWSAccountId, AwsAccountId from LogGroup

    Cependant, la requête suivante est prise en charge car le nom du champ (@logStream) est identique dans les deux groupes de journaux :

    Select a.`@logStream`, b.`@logStream` from Table A INNER Join Table B on a.id = b.id

  • Les fonctions et expressions doivent agir sur les noms de champs et faire partie d'une instruction SELECT avec un groupe de journaux spécifié dans la clause FROM.

    Par exemple, cette requête n'est pas prise en charge :

    SELECT cos(10) FROM LogGroup

    Cette requête est prise en charge :

    SELECT cos(field1) FROM LogGroup

  • Lorsque vous utilisez des commandes SQL ou PPL, entourez certains champs de backticks pour les interroger correctement. Les champs contenant des caractères spéciaux (non alphabétiques et non numériques) doivent être cochés. Par exemple, joignez @messageOperation.Export, et entre Test::Field backticks. Il n'est pas nécessaire de placer les champs avec des noms purement alphabétiques en backticks.

    Exemple de requête avec des champs simples :

    SELECT SessionToken, Operation, StartTime  FROM `LogGroup-A`
LIMIT 1000;

    Requête similaire avec backticks ajoutés :

    SELECT `@SessionToken`, `@Operation`, `@StartTime`  FROM `LogGroup-A` LIMIT 1000;