Commandes de recherche > stats, chart et timechart

Les commandes stats, chart et timechart sont des commandes extrêmement utiles (surtout stats). Lorsque j'ai commencé à apprendre à utiliser les commandes de recherche Splunk, j'ai eu du mal à comprendre les différents avantages de chaque commande, et notamment la façon dont la clause BY affecte le résultat d'une recherche. Finalement, c’est en comparant les résultats (avec quelques essais et beaucoup d’erreurs) que j'ai compris ce qui différencie les commandes. 

Ces trois commandes sont des commandes de transformation. Une commande de transformation prend les données d'événement et les convertit en tableau de résultats organisé. Vous pouvez utiliser ces trois commandes pour calculer des statistiques : décompte, somme ou moyenne par exemple. 

Remarque : dans les exemples qui suivent et dans la documentation Splunk, le mot-clé BY est affiché en majuscules pour plus de lisibilité. Vous pouvez le taper aussi bien en minuscules qu’en majuscules dans vos recherches.

Tableau de résultats de la commande stats

Commençons par la commande stats. Nous allons compter le nombre d’événements de chaque code de statut HTTP.

... | stats count BY status

Le nombre d'événements pour chaque code de statut unique est indiqué dans une nouvelle ligne d'un tableau, dans l’onglet Statistiques :

Très simplement, les valeurs des champs (200, 400, 403, 404) deviennent des en-têtes de lignes dans le tableau de résultats. 

Pour la commande stats, les champs que vous spécifiez dans la clause BY servent à grouper les résultats. Par exemple, nous recevons des événements de trois hôtes : www1, www2 et www3. Si nous ajoutons le champ host à notre clause BY, les résultats sont répartis en des groupes distincts.  

... | stats count BY status, host

Chaque combinaison unique de statut et d’hôte s'affiche sur une nouvelle ligne du tableau de résultats.

Chaque champ spécifié dans la clause BY devient une nouvelle colonne dans le tableau de résultats. Vous divisez les lignes par statut d'abord, puis par hôte. Les champs que vous spécifiez dans la clause BY de la commande stats sont appelés champs .

Dans cet exemple, les clients peuvent réaliser cinq actions sur notre site web : addtocart, changequantity, purchase, remove et view. 

Ajoutons les actions à la recherche.

... | stats count BY status, host, action

Vous divisez les lignes par statut d'abord, puis par hôte et enfin par action. Ci-dessous se trouve une partie du tableau de résultats généré lorsque nous ajoutons le champ action à la clause BY :

L’un des grands avantages de la commande stats est que vous pouvez spécifier plus de deux champs dans la clause BY et créer des tableaux de résultats qui présentent des calculs statistiques très granulaires.

Tableau de résultats de la commande chart

En reprenant la même recherche de base, comparons les résultats produits par la commande chart à ceux de la commande stats.

Si vous ne spécifiez qu’un seule champ BY, les résultats des commandes stats et chart sont identiques. C’est lorsque vous utilisez la commande chart avec deux champs BY que vous voyez vraiment la différence. 

Souvenez-vous que les résultats renvoyés par la commande stats avec deux champs BY sont :

Remplaçons maintenant la commande stats par la commande chart dans la recherche.

... | chart count BY status, host

La recherche renvoie les résultats suivants : 

La commande chart utilise le premier champ de la clause BY, status pour grouper les résultats. Pour chaque valeur unique du champ status, les résultats apparaissent sur une nouvelle ligne. Ce premier champ BY est appelé champ . La commande chart utilise le second champ de la clause BY, host pour diviser les résultats en colonnes. Ce second champ BY est appelé champ . Les valeurs du champ host deviennent des titres de colonne.

Observez les résultats du code d'état 403 dans les deux tableaux de résultats. Avec la commande stats, il n’y a aucun résultat pour le code de statut 403 et les hôtes www1 et www3. Avec la commande chart, lorsqu’il n’y a pas d'événement pour le champ contenant la valeur du champ , un 0 est renvoyé. 

Une différence essentielle entre les commandes stats et chart est le nombre de champs que vous pouvez spécifier dans la clause BY.

Avec la commande stats, vous pouvez, dans la clause BY, spécifier une liste de champs qui seront tous des champs . La syntaxe de la clause BY de la commande stats est :

BY

Pour la commande chart, vous pouvez spécifier deux champs au maximum. Un champ et un champ .  

La commande chart offre deux manières de préciser ces champs dans la clause BY. Par exemple :

... | chart count BY status, host

... | chart count OVER status BY host

La syntaxe de la clause BY de la commande chart est :

[ BY ] | [ OVER ] [BY ] ]

L’avantage de la commande chart est qu’elle crée un tableau de résultats consolidé plus pratique pour créer des graphiques. Vous allez voir ce que j’entends par là.

Visualisation des commandes stats et chart

Lorsque vous exécutez les commandes stats et chart, les données d'événement sont transformées en tableaux de résultats qui apparaissent sur l’onglet Statistiques. Cliquez sur l’onglet Visualisation pour générer un graphique à partir des résultats. Voici la visualisation du tableau de résultats de la commande stats :

Le champ status constitue l’axe des abscisses et les champs host et count forment la série de données. La plage des valeurs de décompte (count) forme l’axe des ordonnées.

Ce graphique pose plusieurs problèmes :

1. On a plusieurs valeurs pour le même code de statut sur l’axe des abscisses. 
2. Les valeurs host (www1, www2 et www3) sont des valeurs de type chaîne et ne peuvent être mesurées sur le graphique. Le host apparaît dans la légende mais il n’y a pas de colonne bleue sur le graphique.
   
   

Pour toutes ces raisons, le graphique est confus et il ne transmet par les informations contenues dans le tableau de résultats.

Si vous pouvez créer une visualisation utilisable à partir du tableau de résultats de la commande stats, la visualisation n’est utile que lorsque vous spécifiez un seul champ dans la clause BY. 

Il vaut mieux utiliser la commande chart lorsque vous voulez créer une visualisation avec deux champs de clause BY :

Le champ status constitue l’axe des abscisses et les valeurs host forment la série de données. La plage des valeurs de décompte (count) forme l’axe des ordonnées.

Et la commande timechart ?

Lorsque vous utilisez la commande timechart, le tableau de résultats est toujours groupé en fonction de l’horodatage de l’événement (le champ _time). La valeur de temps joue le rôle de dans le tableau de résultats. Dans la clause BY, vous allez donc spécifier un seule champ, le champ .  Par exemple, cette recherche génère un décompte et spécifie le champ status comme champ  :

... | timechart count BY status

Cette recherche produit ce tableau de résultats :

Si vous effectuez plutôt une recherche par champ host, vous obtenez le tableau de résultats suivant :

Les incréments de temps que vous voyez dans la colonne _time dépendent de la plage temporelle de la recherche ou des arguments spécifiés dans la commande timechart.  Dans les exemples précédents, la plage spécifiée était All time et il n’y avait que quelques semaines de données. Comme nous n’avions pas précisé de span, une fourchette par défaut était utilisée. Dans cette situation, la fourchette par défaut est de 1 jour.

Si vous précisez une période telle que Last 24 hours pour les 24 dernières heures, la fourchette par défaut est de 30 minutes. La section Utilisation de la documentation de la commande timechart indique les fourchettes par défaut des périodes les plus courantes. Ce tableau de résultats présente la fourchette par défaut de 30 minutes :

La commande timechart inclut plusieurs options qui ne sont pas disponibles dans les commandes stats et chart. Par exemple, vous pouvez préciser une fourchette comme celle que nous avons dans cette recherche :

... | timechart span=12h count BY host

Dans cet exemple, les incréments de 12 heures dans le tableau de résultats sont basés sur l’heure d’exécution de la recherche (heure locale) et son alignement sur l’heure UNIX (parfois appelée heure Epoch).

Remarque : vous pouvez préciser d'autres options avec la commande timechart, que nous allons explorer dans un article distinct.

Comment ces résultats s'affichent-ils sous forme graphique ? Sur l’onglet Visualisation, vous voyez que _time forme l’axe des abscisses. L’axe indique les valeurs minuit et midi pour chaque date. Toutefois, les colonnes qui représentent les données commencent à 1700 chaque jour et se terminent à 0500 le jour suivant.

Le champ précisé dans la clause BY forme la série de données. La plage des valeurs de décompte (count) forme l’axe des ordonnées.

En résumé

Les commandes stats, chart et timechart présentent des similarités, mais il faut faire attention aux clauses BY que vous utilisez avec elles.

• Utilisez la commande stats quand vous voulez créer des tableaux de résultats qui présentent des calculs statistiques granulaires.
• Utilisez la commande stats quand vous avez besoin de spécifier au moins 3 champs dans la clause BY.
• Utilisez la commande chart quand vous voulez créer des tableaux de résultats qui présentent des calculs consolidés et résumés.
• Utilisez la commande chart pour créer des visualisations à partir des données du tableau de résultats.
• Utilisez la commande timechart pour créer des tableaux de résultats et des graphiques temporels.

Fais de SPL ta deuxième langue – Laura

Références

Autres articles :

• Commandes de recherche > stats, eventstats et streamstats

Documentation Splunk :

• Commande stats : https://docs.splunk.com/Documentation/Splunk/latest/SearchReference/Stats
• Commande chart : https://docs.splunk.com/Documentation/Splunk/latest/SearchReference/Chart
• Commande timechart : https://docs.splunk.com/Documentation/Splunk/latest/SearchReference/Timechart

*Cet article est une traduction de celui initialement publié sur le blog Splunk anglais.