Tracciamento di serie temporali

Creare dashboard e selezionare le serie temporali da tracciare. Utilizzare query personalizzate e funzionalità avanzate come filtro, aggregazione, granularità, operazioni aritmetiche e funzioni per lavorare con le serie temporali.

Creazione di un dashboard

Per creare un dashboard con i dati di serie temporali da Cognite Data Fusion (CDF):

1. Accedere all'istanza di Grafana e creare un dashboard.

2. Utilizzare le schede query sotto l'area del grafico principale per selezionare le serie temporali per il dashboard:

   • Ricerca nelle serie temporali: recuperare dati da una serie temporale specifica. Iniziare a digitare il nome o la descrizione della serie temporale e selezionarla dall'elenco a discesa.

     Specificare l'aggregazione e la granularità direttamente nella query. Per impostazione predefinita, l'aggregazione è impostata su media e la granularità è determinata dall'intervallo di tempo selezionato del grafico.

     suggerimento

     Se lo si desidera, impostare un'etichetta personalizzata e utilizzare il formato {{property}} per estrarre dati dalla serie temporale. È possibile utilizzare tutte le proprietà della serie temporale per definire un'etichetta, ad esempio {{name}} - {{description}} o {{metadata.key1}}.

   • Serie temporale di asset: recuperare dati dalla serie temporale corrrelata a un asset specifico. Iniziare a digitare il nome o la descrizione dell'asset e selezionarlo dall'elenco a discesa. Se lo si desidera, decidere se includere la serie temporale da asset secondari.

   • Serie temporale da query personalizzata: recuperare la serie temporale che corrisponde a una query.

3. La serie temporale corrispondente alla selezione verrà resa nell'area del grafico. Regolare l'intervallo di tempo in modo da visualizzare i dati rilevanti.

Utilizzo di query personalizzate

Le query personalizzate offrono un controllo a granularità fine sulla selezione dei dati della serie temporale. È possibile utilizzare operazioni aritmetiche, funzioni e una sintassi speciale per recuperare serie temporali sintetiche. Questa sezione illustra le limitazioni correlate al filtraggio dei dati e spiega come utilizzare in modo efficace i filtri regex e lato server.

Definizione di una query

Per richiedere una serie temporale, specificare una query con i parametri all'interno. Ad esempio, per eseguire una query per una serie temporale in cui id è uguale a 123, specificare ts{id=123}.

È possibile richiedere serie temporali utilizzando id, externalId o filtri serie temporale.

Per le serie temporali sintetiche, è possibile specificare diversi tipi di proprietà:

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

Per creare serie temporali sintetiche complesse, è possibile combinare i tipi in una singola query:

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

Filtro

Le query supportano anche il filtro in base alle proprietà delle serie temporali che si applicano come operatore AND logico. Ad esempio, la query seguente trova le serie temporali:

• che appartengono a un asset con id uguale a 123
• dove name inizia con "Begin"
• dove name non termina con "end"
• dove name non è uguale a "Begin query"

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

La sintassi della query contiene tipi diversi di operatori di uguaglianza:

• = - Uguaglianza stretta. Specifica i parametri per la richiesta di serie temporale a CDF. Utilizzare con gli attributi filtro.
• =! - Diseguaglianza stretta. Filtra le serie temporali recuperate tramite proprietà non uguali alla stringa. Supporta valori stringa, numerici e booleani.
• =~ - Uguaglianza regex. Filtra le serie temporali recuperate tramite proprietà corrispondenti all'espressione regolare. Supporta i valori stringa.
• !~ - Diseguaglianza regex. Filtra le serie temporali recuperate tramite proprietà che non corrispondono all'espressione regolare. Supporta i valori stringa.

È anche possibile filtrare in base ai metadati:

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

La precedente query richiede serie temporali dove:

• externalIdPrefix è uguale a "test"
• metadata.key1 è uguale a "value1"
• metadata.key2 inizia con "value2"

Limitazioni delle query

Quando si eseguono query personalizzate, è importante comprendere le limitazioni sottostanti per il recupero delle serie temporali:

• Filtro lato client: Il connettore applica query regex (=~ per le corrispondenze e !~ per le esclusioni) e filtri di diseguaglianza inesatta (=!) sul lato client. Questo processo si verifica dopo il recupero iniziale di un massimo di 1.000 elementi di serie temporali da Cognite Data Fusion (CDF). Con questo approccio è possibile che non tutte le serie temporali rilevanti vengano incluse nel subset recuperato se il numero totale supera 1.000.

• Filtro lato server: Per attenuare questa limitazione, è consigliabile utilizzare il filtro lato server se possibile. A tale scopo, applicare filtri di uguaglianza rigidi (=) su proprietà del filtro delle serie temporali specifiche. In questo modo, si restringe il set di serie temporali recuperate da CDF e si rende possibile l'applicazione di filtri lato client successivi a un set di dati più mirato. In questo modo, ci si assicura che tutte le serie temporali rilevanti, soprattutto quelle di interesse, siano incluse nel set di dati iniziale recuperato da CDF.

Combinare il filtro lato server con metadati o attributi specifici per ridefinire l'ambito della query prima di applicare i filtri regex o altri filtri lato client. Questo approccio aumenta in modo significativo le possibilità di selezionare tutte le serie temporali di interesse nel dashboard di Grafana.

Aggregazione, granularità e allineamento

È possibile specificare l'aggregazione e la granularità per ogni serie temporale utilizzando gli elenchi a discesa nell'interfaccia utente.

Se, ad esempio, l'aggregazione è impostata su average e la granularità è uguale a 1h, tutte le query richiedono punti dati con l'aggregazione e la granualità selezionate. Per impostazione predefinita, l'aggregazione con le serie temporali sintetiche viene allineata a giovedì 00:00:00 UTC, 1 gennaio 1970.

Con la sintassi della query delle serie temporali sintetiche, è possibile definire aggregazione, granularità e allineamento per ogni serie temporale separatamente:

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

La query esegue l'override dei valori di aggregazione e granularità impostati nell'interfaccia utente. Per un elenco degli aggregati supportati, vedere la documentazione dell'API.

Operazioni aritmetiche

È possibile applicare operazioni aritmetiche per combinare le serie temporali. Ad esempio:

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

Il risultato della query precedente è un singolo tracciato in cui i punti dati sono valori sommati di ogni serie temporale.

In questo esempio, la query ts{name~="test1.*"} può restituire più di una serie temporale, ma supponiamo che restituisca tre serie temporali con ID 111, 222 e 333:

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

Il risultato della query è tre tracciati, una combinazione di valori di serie temporali sommati restituiti dalla prima e la seconda espressione nella query. I tracciati risultanti rappresentano queste query:

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

È possibile visualizzare un esempio di questo comportamento (ogni espressione ts{} restituisce due serie temporali) nell'immagine seguente (si notino le etichette sotto il grafico).

Functions

Supportiamo un'ampia gamma di funzioni applicabili alle serie temporali sintetiche:

• Trigonometriche: sin(ts{}), cos(ts{}), pi().
• Funzioni a lunghezza variabile: max(ts{}, ...), min(ts{}, ...), avg(ts{}, ...).
• Algebriche: ln(ts{}), pow(ts{}, exponent), sqrt(ts{}), exp(ts{}), abs(ts{}).
• Gestione degli errori: on_error(ts{}, default_value). Vedere Gestione degli errori per i calcoli.
• Serie temporale stringa: map(expression, [list of strings to map from], [list of values to map to], default_value). Vedere Serie temporali stringa.

Gestione degli errori per i calcoli

La funzione on_error(ts{...}) consente il rendering del grafico anche se compaiono eccezioni. Gestisce errori come:

• BAD_DOMAIN: se vengono forniti intervalli di input non corretti. Ad esempio, divisione per zero o radice quadrata di un numero negativo.
• OVERFLOW: se il risultato è maggiore di 10^100 in valore assoluto.

Se si incontrano, anziché restituire un valore per il timestamp, CDF restituisce un campo errore con un messaggio di errore. Per evitarli, è possibile eseguire il wrapping dell'espressione secondaria nella funzione on_error():

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

Serie temporale stringa

La funzione map() può gestire le serie temporali con valori stringa per convertire le stringhe in doppi. Se, ad esempio, una serie temporale per una valvola può avere i valori "OPEN" o "CLOSED", è possibile convertirla in un numero con:

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

"OPEN" è mappato a 1, "CLOSED" a 0 e tutto il resto a -1.

Gli aggregati sulle serie temporali stringa sono al momento non supportati. Tutte le serie temporali stringa sono considerate serie temporali a fasi.

Conversione delle unità

Se una serie temporale ha una unitExternalId definita, è possibile convertire i relativi valori in un'altra unità nella stessa quantità quando si eseguono query personalizzate sui dati.

Esempio:

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

È possibile scegliere targetUnit o targetUnitSystem per ogni aggregato o serie temporale. L'unità di destinazione scelta deve essere compatibile con quella originale.

Quando si eseguono query su punti dati utilizzando serie temporali sintetiche, le unità per i valori non vengono conservate. Ciò significa che è possibile aggiungere valori da una serie temporale temperatura a una serie temporale distanza, anche se non è fisicamente accurato.

Nota Se si tenta di accedere alle proprietà unit o unitExternalId di ogni serie temporale nel campo etichetta, Grafana restituirà l'unità originale della serie temporale, non l'unità dei punti dati.

Visualizzazione dei dati delle serie temporali da istanze di modelli dati

È possibile visualizzare i dati delle serie temporali da istanze di modelli dati di CDF:

1. Nella scheda Modelli dati selezionare il modello dati e la versione.

2. Specificare la query.

   importante

   Aggiungere __typename e externalId sotto i campi che contengono le serie temporali. In questo esempio, sotto temperature e pressure:

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