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 traitement canalisé (PPL)
Cette section contient une introduction de base à l'interrogation des CloudWatch journaux à l'aide de OpenSearch PPL. Avec PPL, vous pouvez récupérer, interroger et analyser des données à l'aide de commandes groupées, ce qui facilite la compréhension et la composition de requêtes complexes. Sa syntaxe est basée sur les canaux Unix et permet d'enchaîner les commandes pour transformer et traiter les données. Avec PPL, vous pouvez filtrer et agréger des données, et utiliser un ensemble complet de fonctions mathématiques, de chaîne, de date, conditionnelles et autres pour l'analyse.
L'inclusion `SOURCE` dans une requête PPL est un moyen utile de spécifier les groupes de journaux, les index de champs et les sources de données à inclure dans une requête lorsque vous utilisez l'API AWS CLI or pour créer une requête. La `SOURCE` commande est prise en charge uniquement dans l'API AWS CLI and, pas dans la CloudWatch console. Lorsque vous utilisez la CloudWatch console pour démarrer une requête, vous utilisez l'interface de console pour spécifier les groupes de journaux ainsi que le nom et le type de source de données.
`aws:fieldIndex`À 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. Les groupes de journaux pertinents sont automatiquement sélectionnés en fonction des champs spécifiés dans la `filterIndex` commande. Cela réduit 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. `aws:fieldIndex`À utiliser pour spécifier le nom du champ, ainsi que le nom et la valeur du champ dans la commande source afin d'interroger uniquement les données indexées contenant le champ et la valeur spécifiés. Pour de plus amples informations, consultez [Créez des index de champs pour améliorer les performances des requêtes et réduire le volume de numérisation](CloudWatchLogs-Field-Indexing.md).
Vous pouvez utiliser OpenSearch PPL pour les requêtes de groupes de journaux dans la classe de journal standard.
**Note**
Pour plus d'informations sur toutes les commandes de requête OpenSearch PPL prises en charge dans les CloudWatch journaux et des informations détaillées sur la syntaxe et les restrictions, consultez la section [Commandes PPL prises en charge](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/supported-ppl.html) dans le Guide du développeur OpenSearch de services.
Pour plus d'informations sur les autres langages de requête, vous pouvez utiliser [CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html), [OpenSearch Service SQL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_SQL.html) et [CloudWatch Metrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html)
| Commande ou fonction | Exemple de requête | Description |
| --- | --- | --- |
| `fields` | `fields field1, field2` | Affiche un ensemble de champs qui doivent être projetés. |
| `join` | `LEFT JOIN left=l, right=r on l.id = r.id `join_right_lg` \| fields l.field_1, r.field_2` | Joint deux ensembles de données. |
| `where` | `where field1="success" \| where field2 != "i-023fe0a90929d8822" \| fields field3, field4, field5,field6 \| head 1000` | Filtre les données en fonction des conditions que vous spécifiez. |
| `aws:fieldIndex` | `source = [`aws:fieldIndex`="region", `region` = "us-west-2"] \| where status = 200 \| head 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. |
| `stats` | `stats count(), count(field1), min(field1), max(field1), avg(field1) by field2 \| head 1000` | Effectue des agrégations et des calculs |
| `parse` | `parse field1 ".*/(?[^/]+$)" \| where field2 = "requestId" \| fields field1, field2 \| head 1000` | Extrait un modèle d'expression régulière (regex) d'une chaîne et affiche le modèle extrait. Le modèle extrait peut également être utilisé pour créer de nouveaux champs ou filtrer des données. |
| `sort` | `stats count(), count(field1), min(field1) as field1Alias, max(`field1`), avg(`field1`) by field2 \| sort -field1Alias \| head 1000` | Triez les résultats affichés par nom de champ. Utilisez le tri - FieldName pour trier par ordre décroissant. |
| `eval` | `eval field2 = field1 * 2 \| fields field1, field2 \| head 20` | Modifie ou traite la valeur d'un champ et la stocke dans un autre champ. Cela est utile pour modifier mathématiquement une colonne, appliquer des fonctions de chaîne à une colonne ou appliquer des fonctions de date à une colonne. |
| `rename` | `rename field2 as field1 \| fields field1;` | Renomme un ou plusieurs champs dans les résultats de recherche. |
| `head` | `fields `@message` \| head 20` | Limite les résultats de requête affichés aux N premières lignes. |
| `top` | `top 2 field1 by field2` | Recherche les valeurs les plus fréquentes pour un champ. |
| `dedup` | `dedup field1 \| fields field1, field2, field3` | Supprime les entrées dupliquées en fonction des champs que vous spécifiez. |
| `rare` | `rare field1 by field2` | Recherche les valeurs les moins fréquentes de tous les champs de la liste de champs. |
| `subquery` | `where field_1 IN [ search source= `subquery_lg` \| fields field_2 ] \| fields id, field_1 ` | Exécute des requêtes complexes et imbriquées dans vos instructions PPL. |
| `trendline` | `trendline sma(2, field1) as field1Alias` | Calcule les moyennes mobiles des champs. |
| `eventStats` | `eventstats sum(field1) by field2` | Enrichissez les données de vos événements grâce à des statistiques récapitulatives calculées. Il analyse les champs spécifiés au sein de vos événements, calcule diverses mesures statistiques, puis ajoute ces résultats à chaque événement d'origine sous forme de nouveaux champs. |
| `expand` | `eval tags_array_string = json_extract(`@message`, '$.tags')\| eval tags_array = json_array(json_extract(tags_string, '$[0]'), json_extract(tags_string, '$[1]'))\| expand tags_array as color_tags` | Décompose un champ contenant plusieurs valeurs en lignes distinctes, en créant une nouvelle ligne pour chaque valeur du champ spécifié. |
| `fillnull` | `fields `@timestamp`, error_code, status_code \| fillnull using status_code = "UNKNOWN", error_code = "UNKNOWN"` | Remplit les champs nuls avec la valeur que vous fournissez. Il peut être utilisé dans un ou plusieurs domaines. |
| `flatten` | `eval metadata_struct = json_object('size', json_extract(metadata_string, '$.size'), 'color', json_extract(metadata_string, '$.color')) \| flatten metadata_struct as (meta_size, meta_color) ` | Aplatit un champ. Le champ doit être de ce type : `struct` ou`array>`. |
| `cidrmatch` | `where cidrmatch(ip, '2003:db8::/32') \| fields ip ` | Vérifie si l'adresse IP spécifiée se situe dans la plage CIDR donnée. |
| `fieldsummary` | `where field1 != 200 \| fieldsummary includefields= field1 nulls=true` | Calcule les statistiques de base pour chaque champ (nombre, nombre distinct, min, max, avg, stddev et moyenne). |
| `grok` | `grok email '.+@%{HOSTNAME:host}' \| fields email, host` | Analyse un champ de texte à l'aide d'un motif grok et ajoute les résultats au résultat de recherche. |
| Fonctions de chaîne | `eval field1Len = LENGTH(field1) \| fields field1Len` | Fonctions intégrées dans PPL qui peuvent manipuler et transformer des chaînes et des données de texte dans les requêtes PPL. Par exemple, convertir des majuscules, combiner des chaînes, extraire des parties et nettoyer du texte. |
| Fonctions date-heure | `eval newDate = ADDDATE(DATE('2020-08-26'), 1) \| fields newDate ` | Fonctions intégrées pour gérer et transformer les données de date et d'horodatage dans les requêtes PPL. Par exemple, date\_add, date\_format, datediff, date-sub, timestampadd, timestampdiff, current\_timezone, utc\_timestamp et current\_date. |
| Fonctions de condition | `eval field2 = isnull(field1) \| fields field2, field1, field3` | Fonctions intégrées qui vérifient les conditions de champ spécifiques et évaluent les expressions de manière conditionnelle. Par exemple, si le champ 1 est nul, renvoie le champ 2. |
| Fonctions mathématiques | `eval field2 = ACOS(field1) \| fields field1` | Fonctions intégrées pour effectuer des calculs mathématiques et des transformations dans les requêtes PPL. Par exemple, abs (valeur absolue), round (arrondit les nombres), sqrt (racine carrée), pow (calcul de puissance) et ceil (arrondit au nombre entier le plus proche). |
| CryptoGraphic fonctions | `eval crypto = MD5(field)\| head 1000` | Pour calculer le hachage d'un champ donné |
| Fonctions JSON | `eval valid_json = json('[1,2,3,{"f1":1,"f2":[5,6]},4]') \| fields valid_json` | Fonctions intégrées pour gérer le JSON, notamment les tableaux, l'extraction et la validation. Par exemple, json\_object, json\_array, to\_json\_string, json\_array\_length, json\_extract, json\_keys et json\_valid. |
## Étendue de la requête
L'inclusion de SOURCE dans une requête est un moyen utile de spécifier les groupes de journaux à inclure dans une requête lorsque vous utilisez l'API AWS CLI or pour créer une requête. La commande SOURCE n'est prise en charge que dans l'API AWS CLI and, pas dans la CloudWatch console. Lorsque vous utilisez la CloudWatch console pour démarrer une requête, vous utilisez l'interface de console pour spécifier les groupes de journaux ainsi que le nom et le type de source de données.
La commande source de PPL permet désormais de les spécifier de plusieurs manières :
1. Groupe de journaux
1. Index des champs - Nouveau
1. Source et type de données - Nouveau
### 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
```
source = [lg:`/aws/lambda/my-function`] | where status = 200 | head 10
```
### Index des champs
La sélection de sources basée sur l'index des champs réduit la quantité de données demandées en limitant les résultats aux seules données indexées lorsque vos filtres ciblent les champs qui ont été indexés. Les groupes de journaux pertinents sont automatiquement sélectionnés en fonction des champs spécifiés dans la `filterIndex` commande. 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](CloudWatchLogs-Field-Indexing.md).
`aws:fieldIndex`À 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 PPL, `aws:fieldIndex` est utilisé pour spécifier quelles paires clé-valeur doivent être traitées comme des index. La syntaxe est la suivante
```
source = [`aws:fieldIndex`="region", `region` = "us-west-2"] | where status = 200 | head 10
```
Où :
1. ``aws:fieldIndex`="region"`identifie la région en tant qu'index de champ.
1. Remarque : Au lieu de =, les clients peuvent utiliser IN pour spécifier plusieurs index (exemple ci-dessous)
1. ``region`="us-west-2"`identifie la condition de filtre à appliquer
1. Remarque : Au lieu de =, les clients peuvent utiliser IN pour spécifier plusieurs valeurs (exemple ci-dessous)
Les clients peuvent spécifier plusieurs FieldIndexes comme suit
```
source = [`aws:fieldIndex` IN ("status", "region"), `status` = 200, `region` IN ("us-west-2", "us-east-1")] | head 10
```
### Source et type 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.
```
source = [ds:`data_source.type`] | where status = 200 | head 10
```
#### PPL pris en charge pour les requêtes de sources de données
Pour prendre en charge le cas d'utilisation de l'interrogation de sources de données dans PPL, vous pouvez utiliser la clause de sélection de source dynamique. À l'aide de cette syntaxe, vous pouvez interroger des sources de données en les spécifiant dans la commande de recherche. Vous pouvez spécifier jusqu'à 10 sources de données.
**Syntaxe**
```
source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`, ...ds:`DataSourcen.Typen`]
```
**Exemple de requête**
```
search source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`] | fields field1, field2
```
### Exemple combiné
Les clients peuvent spécifier tous les opérateurs de sélection de source dans n'importe quel ordre et les résultats seront 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.
```
search source=[
ds:`DataSource1.Type1`,
lg:`/aws/lambda/my-function-1`,
`aws:fieldIndex` IN ("status"), `status` = 200
]
```
## Restrictions
Les restrictions suivantes s'appliquent lorsque vous utilisez OpenSearch PPL pour effectuer des requêtes dans CloudWatch Logs Insights.
+ Vous ne pouvez pas utiliser de commandes de jointure ou de sous-requête avec des requêtes de source de données.