Représentation graphique de séries temporelles

Créez des tableaux de bord et sélectionnez les séries temporelles que vous voulez représenter graphiquement. Utilisez des requêtes personnalisées et des fonctionnalités avancées telles que le filtrage, l’agrégation, la granularité, les opérations arithmétiques et des fonctions pour travailler avec des séries temporelles.

Création d’un tableau de bord

Pour créer un tableau de bord avec des données de séries temporelles à partir de Cognite Data Fusion (CDF) :

1. Connectez-vous à votre instance Grafana et créez un tableau de bord.

2. Utilisez les onglets de requêtes sous la zone du graphique principal pour sélectionner des séries temporelles pour votre tableau de bord :

   • Recherche de séries temporelles : récupérez des données depuis une série temporelle spécifique. Commencez à saisir le nom ou la description de la série temporelle, et sélectionnez-la depuis la liste déroulante.

     Indiquez l’agrégation et la granularité directement dans la requête. Par défaut, l’agrégation est définie sur moyenne, et la granularité est déterminée pour l’intervalle de temps sélectionné pour le graphique.

     conseil

     Vous pouvez également créer un libellé personnalisé et utiliser le format {{property}} pour extraire des données de la série temporelle. Vous pouvez utiliser toutes les propriétés de séries temporelles spécifiques pour définir un libellé, par exemple, {{name}} - {{description}} ou {{metadata.key1}}.

   • Séries temporelles issues d’actifs : récupérez des données depuis des séries temporelles associées à un actif donné. Commencez à saisir le nom ou la description de l’actif, et sélectionnez-le depuis la liste déroulante. Vous pouvez également décider d’inclure ou non des séries temporelles à partir de sous-actifs.

   • Requête personnalisée de séries temporelles : récupérez une série temporelle correspondant à une requête.

3. La série temporelle correspondant à votre sélection sera produite dans la zone du graphique. Ajustez au besoin la période pour afficher les données pertinentes.

Utilisation de requêtes personnalisées

Les requêtes personnalisées permettent de contrôler plus précisément la sélection des données des séries temporelles. Vous pouvez utiliser des opérations arithmétiques, des fonctions et une syntaxe spéciale pour récupérer des séries temporelles synthétiques. Cette section décrit également les limites liées au filtrage des données et la manière d’utiliser efficacement les filtres regex et côté serveur.

Définition d’une requête

Pour demander des séries temporelles, spécifiez une requête contenant les paramètres. Par exemple, pour demander une série temporelle dont l’id est 123, spécifiez ts{id=123}.

Vous pouvez demander des séries temporelles avec un id, un externalId ou des filtres de séries temporelles.

Pour les séries temporelles synthétiques, vous pouvez spécifier plusieurs types de propriétés :

• bool : ts{isString=true} ou ts{isStep=false}
• string ou number : ts{id=123} ou ts{externalId='external_123'}
• array : ts{assetIds=[123, 456]}
• object : ts{metadata={key1="value1", key2="value2"}}

Pour créer des séries temporelles synthétiques complexes, vous pouvez associer les types dans une seule requête :

ts{name="test", assetSubtreeIds=[{id=123}, {externalId="external_123"}]}

Filtrage

Les requêtes permettent également un filtrage selon les propriétés des séries temporelles avec application comme AND logique. Par exemple, la requête ci-dessous permet de trouver des séries temporelles :

• appartenant à un actif avec un id égal à 123
• où name commence par "Begin"
• où name ne se termine pas par "end"
• où name n’est pas égal à "Begin query"

ts{assetIds=[123], name=~"Begin.*", name!~".*end", name!="Begin query"}

La syntaxe de la requête inclut différents types d’opérateurs d’égalité :

• = - égalité stricte. Spécifie des paramètres pour la requête de séries temporelles à CDF. À utiliser avec des attributs de filtrage.
• =! - inégalité stricte. Filtre les séries temporelles extraites en fonction de propriétés qui ne sont pas égales à la chaîne. Prend en charge des valeurs de chaînes, numériques et booléennes.
• =~ - égalité regex. Filtre les séries temporelles extraites en fonction de propriétés qui correspondent à l’expression régulière. Prend en charge des valeurs de chaînes.
• !~ - inégalité regex. Filtre les séries temporelles extraites en fonction de propriétés qui ne correspondent pas à l’expression régulière. Prend en charge des valeurs de chaînes.

Vous pouvez aussi filtrer en fonction de métadonnées :

ts{externalIdPrefix="test", metadata={key1="value1", key2=~"value2.*"}}

La requête ci-dessus demande des séries temporelles où :

• externalIdPrefix est égal à "test"
• metadata.key1 est égal à "value1"
• metadata.key2 commence par "value2"

Limites concernant les requêtes

Lors de l’exécution de requêtes personnalisées, il est important de comprendre les limites sous-jacentes à la récupération des séries temporelles :

• Filtrage côté client : Le connecteur applique des requêtes regex (=~ pour les correspondances et !~ pour les exclusions) et des filtres d’inégalité (=!) côté client. Ce processus a lieu après la récupération initiale d’un maximum de 1 000 éléments de séries temporelles depuis Cognite Data Fusion (CDF). De ce fait, il se peut que toutes les séries temporelles appropriées ne soient pas incluses dans le sous-ensemble récupéré si leur nombre total est supérieur à 1 000.

• Filtrage côté serveur : Pour atténuer cette limitation, il est recommandé d’utiliser le filtrage côté serveur dans la mesure du possible. Pour cela, il convient d’appliquer des filtres d’égalité stricte (=) à des propriétés de filtrage de séries temporelles spécifiques. Ainsi, vous affinez l’ensemble des séries temporelles récupérées à partir de CDF et vous assurez que les filtres côté client suivants sont appliqués à un jeu de données plus ciblé. Ceci est particulièrement utile pour s’assurer que toute les séries temporelles appropriées, notamment celles qui vous intéressent, sont incluses dans le jeu de données initialement récupéré depuis CDF.

Combinez le filtrage côté serveur avec des attributs ou des métadonnées spécifiques pour affiner la portée de votre requête avant d’appliquer des filtres regex ou d’autres filtres côté client. Cette méthode augmente considérablement les chances de sélectionner toutes les séries temporelles qui vous intéressent dans votre tableau de bord Grafana.

Agrégation, granularité et alignement

Vous pouvez spécifier l’agrégation et la granularité pour chaque série temporelle à l’aide des listes déroulantes dans l’interface utilisateur.

Si, par exemple, l’agrégation est définie sur average et la granularité est de 1h, toutes les requêtes demandent des points de données avec l’agrégation et la granularité sélectionnées. Par défaut, l’agrégation avec des séries temporelles synthétiques est alignée sur jeudi 00:00:00 UTC, le 1er janvier 1970.

La syntaxe des requêtes de séries temporelles synthétiques vous permet de définir l’agrégation, la granularité et l’alignement pour chaque série temporelle séparément :

ts{externalId='houston.ro.REMOTE_AI[34]', alignment=1599609600000, aggregate='average', granularity='24h'}

La requête ci-dessus remplace les valeurs d’agrégation et de granularité définies dans l’interface utilisateur. Vous trouverez une liste d’agrégats pris en charge dans la documentation de l’API.

Opérations arithmétiques

Vous pouvez appliquer des opérations arithmétiques pour combiner des séries temporelles. Par exemple :

ts{id=123} + ts{externalId="test"}

Le résultat de la requête ci-dessus est une représentation graphique unique où les points de données sont des valeurs additionnées de chaque série temporelle.

Dans cet exemple, la requête ts{name~="test1.*"} peut retourner plusieurs séries temporelles, mais considérons qu’elle retourne trois séries temporelles avec les ID 111, 222 et 333 :

ts{name~="test1.*"} + ts{id=123}

La requête produit trois représentations graphiques, une combinaison de valeurs de séries temporelles additionnées retournées par la première et la deuxième expressions dans la requête. Les représentations graphiques obtenues représentent ces requêtes :

• ts{id=111} + ts{id=123}
• ts{id=222} + ts{id=123}
• ts{id=333} + ts{id=123}

Vous trouverez un exemple de ce comportement (chaque expression ts{} retourne deux séries temporelles) dans l’image ci-dessous (remarquez les libellés sous le graphique).

Fonctions

Nous prenons en charge un ensemble de fonctions que vous pouvez appliquer à des séries temporelles synthétiques :

• Trigonométriques : sin(ts{}), cos(ts{}), pi().
• Fonctions de longueur variable : max(ts{}, ...), min(ts{}, ...), avg(ts{}, ...).
• Algébriques : ln(ts{}), pow(ts{}, exponent), sqrt(ts{}), exp(ts{}), abs(ts{}).
• Traitement des erreurs : on_error(ts{}, default_value). Voir Traitement des erreurs pour les calculs.
• Séries temporelles de type chaîne : map(expression, [list of strings to map from], [list of values to map to], default_value). Voir Séries temporelles de type chaîne.

Traitement des erreurs pour les calculs

La fonction on_error(ts{...}) permet de produire des graphiques même en présence d’une exception. Elle traite des erreurs telles que :

• BAD_DOMAIN, si les plages d’entrée fournies sont incorrectes. Par exemple, division par zéro, ou la racine carrée d’un nombre négatif.
• OVERFLOW, si le résultat est supérieur à 10^100 en valeur absolue.

En présence de l’une de ces erreurs, au lieu de retourner une valeur pour l’horodatage, CDF retourne un champ d’erreur avec un message d’erreur. Pour les éviter, vous pouvez enrober l’expression ou sous-expression dans la fonction on_error() :

on_error(1/ts{externalId='canBeZero'}, 0)

Séries temporelles de type chaîne

La fonction map() peut traiter des séries temporelles avec des valeurs de chaînes afin de convertir des chaînes en doubles. Si par exemple une série temporelle pour une vanne peut avoir les valeurs "OPEN" ou "CLOSED", vous pouvez la convertir en un nombre avec :

map(TS{externalId='stringstate'}, ['OPEN', 'CLOSED'], [1, 0], -1)

"OPEN" est mappé en 1, "CLOSED" en 0, et tout le reste en -1.

Les agrégations sur les séries temporelles de type chaîne ne sont pas prises en charge actuellement Toutes les séries temporelles de type chaîne sont considérées comme étant des séries temporelles étagées.

Conversion des unités

Si une unitExternalId est définie pour une série temporelle, vous pouvez convertir ses valeurs dans une unité différente pour la même quantité lors de l’interrogation des données via des requêtes personnalisées.

Exemple :

{ts{externalId='temperature_f_houston', targetUnit='temperature:deg_c'} + ts{id='123', targetUnitSystem='SI'}}

Vous avez le choix entre targetUnit et targetUnitSystem pour chaque série temporelle ou agrégation. L’unité cible que vous choisissez doit être compatible avec l’unité d’origine.

Lors de l’interrogation des points de données à l’aide de séries temporelles synthétiques, les unités ne sont pas conservées pour les valeurs. Cela signifie qu’il est possible d’ajouter des valeurs à partir d’une série temporelle de températures à une série temporelle de distances, même si cela n’est pas matériellement pas correct.

Notez que si vous tentez d’accéder aux propriétés unit ou unitExternalId de chaque série temporelle au niveau du champ libellé, Grafana renverra l’unité d’origine de la série temporelle et non l’unité des points de données.

Affichage de données de séries temporelles à partir d’instances de modèles de données

Vous pouvez afficher des données de séries temporelles à partir d’instances de modèles de données de CDF :

1. Sous l’onglet Modèles de données, sélectionnez le modèle de données et la version.

2. Spécifiez la requête.

   Important

   Ajoutez __typename et externalId sous les champs contenant les séries temporelles. Dans cet exemple, sous temperature et pressure :

   {
     listPump {
       items {
         temperature {
           __typename
           externalId
         }
         pressure {
           __typename
           externalId
         }
       }
     }
   }