Lire chaque valeur brute d’une année serait lent et ne tiendrait pas sur un graphique. Hermetry résume donc les relevés numériques par minute, par heure et par jour, et lit le résumé qui correspond à la fenêtre demandée. Cette page explique les résumés, la façon dont la résolution est choisie et ce que renvoie chaque fonction d’agrégation.
Les résumés
Pour chaque clé numérique de chaque appareil, le stockage conserve cinq valeurs par intervalle :
| Valeur | Signification |
|---|---|
| sum | La somme des valeurs de l’intervalle |
| count | Nombre de valeurs reçues dans l’intervalle |
| min | La plus petite valeur |
| max | La plus grande valeur |
| last | La valeur dont l’horodatage est le plus récent dans l’intervalle |
| Niveau | Intervalle | Conservé pendant |
|---|---|---|
| Agrégats à 1 minute | 1 minute | Votre classe de rétention, 31 jours au maximum |
| Cumuls horaires | 1 heure | Votre classe de rétention complète |
| Cumuls journaliers | 1 jour, de minuit à minuit UTC | Votre classe de rétention complète |
Tous les intervalles sont alignés sur l’UTC. Les résumés par minute sont calculés par une tâche qui s’exécute chaque minute ; les cumuls horaires et journaliers en sont dérivés. Un relevé arrivé après le résumé de sa minute remet cette minute à jour, de sorte que les relevés tardifs sont inclus. Un relevé fraîchement enregistré peut mettre une ou deux minutes à apparaître dans les résumés ; les lectures brutes (fenêtres allant jusqu’à 24 heures) le voient immédiatement.
Les valeurs texte, true/false et JSON ne sont pas résumées. Voir Nombres, texte et valeurs vrai/faux.
Quelle résolution une fenêtre lit
Avec l’intervalle auto (la valeur par défaut pour les graphiques et l’API) :
| Durée de la fenêtre | Résolution |
|---|---|
| Jusqu’à 24 heures | Valeurs brutes, chaque relevé |
| Jusqu’à 10 000 minutes (environ 6,9 jours, donc une fenêtre complète de 7 jours lit déjà des heures) | 1 minute |
| Jusqu’à 10 000 heures (environ 416 jours) | 1 heure |
| Plus long | 1 jour |
Une fenêtre peut contenir au maximum 10 000 intervalles à la résolution choisie. Si vous demandez une résolution fixe qui en nécessiterait davantage (par exemple 1m sur 30 jours), l’API répond 400 avec le code range_too_large. Demandez un intervalle plus large ou une fenêtre plus courte.
Une fenêtre qui remonte plus loin qu’un niveau conservé ne renvoie rien pour la partie manquante. Par exemple, avec la classe de 365 jours, les intervalles 1m de plus de 31 jours sont supprimés ; demandez plutôt 1h.
Les fonctions d’agrégation
Chaque intervalle renvoie une valeur, calculée à partir de ses cinq valeurs :
| Fonction | Valeur par intervalle | Utilisation |
|---|---|---|
avg (par défaut) | sum / count | Températures, niveaux, pressions |
min | La plus petite valeur | Niveau le plus bas, point le plus froid |
max | La plus grande valeur | Pics, « est-ce arrivé » pour les clés 0/1 |
last | La dernière valeur | Relevés de compteurs, états, consignes |
sum | La somme des valeurs | Valeurs déjà exprimées par intervalle (litres sur l’intervalle, événements comptés à 1) |
count | Le nombre de relevés | Taux de remontée, complétude des données |
increase | Hausse d’un compteur | Compteurs d’énergie et d’eau, totaux d’impulsions |
avg est une simple moyenne des relevés de l’intervalle, non pondérée par le temps. Un appareil qui remonte plus souvent sur certaines périodes pèse davantage sur celles-ci.
Lorsqu’une fenêtre brute est lue (jusqu’à 24 heures), l’agrégation n’est pas appliquée : vous obtenez chaque valeur stockée. Les graphiques qui affichent côte à côte des points bruts et un résumé peuvent donc montrer plus de détail pour le dernier jour que pour les jours plus anciens.
increase, pour les compteurs
Les compteurs ne font qu’augmenter (kWh, m³, impulsions) jusqu’à repartir de zéro. increase les transforme en consommation par intervalle :
- La valeur de chaque intervalle est son
lastmoins lelastde l’intervalle précédent. - Si la valeur a baissé (le compteur a été remis à zéro), le
lastde l’intervalle est pris comme la hausse, en partant de zéro. - Le premier intervalle de la fenêtre compte ce qui a augmenté à l’intérieur de celui-ci : son
lastmoins sonmin.
Exemple avec des intervalles horaires d’un compteur d’énergie :
| Heure | last | increase |
|---|---|---|
| 08:00 | 1,200.0 | 4,0 (premier intervalle : last 1 200,0 – min 1 196,0) |
| 09:00 | 1,212.5 | 12.5 |
| 10:00 | 1,221.0 | 8.5 |
| 11:00 | 3.0 | 3,0 (le compteur a été remis à zéro) |
Remarques :
- Une hausse à travers un trou de données est comptée dans le premier intervalle après le trou.
- Un compteur qui repart à zéro puis dépasse son ancienne valeur dans un même intervalle n’est pas détecté comme une remise à zéro.
- Utilisez
increasesur le compteur brut, jamais sur une clé qui est déjà une quantité par intervalle ; utilisezsumpour celle-ci.
Utiliser les résumés
| Où | Comment choisir |
|---|---|
| Cartes de graphiques des tableaux de bord | Le réglage Agrégation de la carte et la fenêtre temporelle du tableau de bord. Voir Cartes de graphiques et Sources de données et paramètres. |
| L’onglet Telemetry de l’appareil | Toujours avg, avec la fenêtre que vous choisissez. Voir L’onglet Telemetry de l’appareil. |
| L’API | bucket et agg sur GET /api/telemetry/series. Voir L’API d’historique. |
| Flux | Le bloc Statistics calcule des valeurs sur une fenêtre de messages dans le flux lui-même. Voir Compteurs, statistiques et chiens de garde. |
Jours et mois locaux
Les cumuls journaliers sont des jours UTC. Pour un total journalier dans un autre fuseau horaire, lisez les intervalles 1h et additionnez vous-même les heures de chaque jour local ; pour les fuseaux au décalage d’une demi-heure, lisez les intervalles 1m (jusqu’à 31 jours en arrière). Voir l’exemple dans L’API d’historique.