Documentazione

Avvolgitore di dati esteri StableNet

Prerequisiti

È necessario un database PostgreSQL con un utente autorizzato a modificare gli oggetti del database. Il wrapper dei dati esterni deve essere installato sulla stessa istanza del server del database.

Esempio: Creare il database infosim di proprietà del ruolo infosim:

export DB_NAME=infosim
mkdir -p /var/lib/pgsql/custom/user_tblspc/${DB_NAME}_tblspc/tab_space/${DB_NAME} \
 /var/lib/pgsql/custom/user_tblspc/${DB_NAME}_tblspc/idx_space/${DB_NAME} && \
 chown -R postgres:postgres /var/lib/pgsql/custom/user_tblspc
psql -Upostgres -c "CREATE ROLE $DB_NAME WITH LOGIN PASSWORD '$DB_NAME';"
psql -Upostgres -c "CREATE TABLESPACE ${DB_NAME}_tab OWNER $DB_NAME \
LOCATION '/var/lib/pgsql/custom/user_tblspc/${DB_NAME}_tblspc/tab_space/$DB_NAME';"
psql -Upostgres -c "CREATE TABLESPACE ${DB_NAME}_idx OWNER $DB_NAME \
LOCATION '/var/lib/pgsql/custom/user_tblspc/${DB_NAME}_tblspc/idx_space/$DB_NAME';"
psql -Upostgres -c "CREATE DATABASE $DB_NAME WITH OWNER $DB_NAME TEMPLATE template0 \
TABLESPACE ${DB_NAME}_tab ENCODING 'UTF8' LC_COLLATE 'de_CH.UTF-8' LC_CTYPE 'de_CH.UTF-8';"

Installazione standard

Installare RPM da SKOOR Repo

dnf install eranger-stablenet-fdw

Configurazione

File di configurazione

/etc/stablenet-fdw/stablenet-fdw.conf

[global]

accept_insecure_certificate = false
                                        # Accept insecure certificates
                                        # (self-signed, expired, etc.)
                                        # when connecting to the web service
default_user = 
                                        # Default user name for the web service.
                                        # This is used in case no authorization 
                                        # is provided by the SQL client.
default_password =
                                        # Default password for the web service.
                                        # This is used in case no authorization 
                                        # is provided by the SQL client.
skoor_auth_url = http://localhost:8094
                                        # URL of the SKOOR web service
                                        # (default: http://localhost:8094)
                                        # This is used to get the StableNet®
                                        # auth tokens.

[webservice]  

url =
                                        # URL of StableNet® the web service

#[webservice_<server_id>]               # Optional, if multiple StableNet® servers 
                                        # are used. Replace <server_id> with a unique
                                        # identifier for the StableNet® server.
                                        # Only alphanumeric lower case characters are allowed.
                                        # Please note, that every webservice section 
                                        # must have a unique identifier if multiple 
                                        # StableNet® servers are used.

#server_name = 
                                        # Unique name of the connected StableNet®
                                        # server. This should be a human readable
                                        # name, not a technical identifier.
                                        # Defaults to server_id if omitted.
#url =
                                        # URL of the StableNet® the web service

Le opzioni possono essere fornite anche da variabili d'ambiente utilizzando il prefisso STABLENET_FDW_WEBSERVICE_ e il nome dell'opzione in maiuscolo (ad esempio STABLENET_FDW_WEBSERVICE_URL). Per le impostazioni di global, GLOBAL deve essere omesso dalla chiave ENV (ad esempio STABLENET_FDW_DEFAULT_USER ).

url è l'URl di base del servizio web StableNet® API. Di solito ha la forma https://<host>:5443/api/1.

È possibile definire più istanze StableNet® utilizzando più sezioni webservice con suffissi unici server_id. server_id viene utilizzato come identificatore interno per ottenere, ad esempio, la stringa di autorizzazione corrispondente da SKOOR Auth. È necessario impostare un server_name appropriato, utilizzato per identificare il server nelle tabelle straniere e aggregate. Questo può essere configurato anche tramite variabili d'ambiente (ad esempio, STABLENET_FDW_WEBSERVICE_URL_TEST, STABLENET_FDW_WEBSERVICE_SERVER_NAME_TEST).

Dopo una modifica della configurazione, il server PostgreSQL deve essere riavviato.

systemctl restart postgresql-13

Inizializzazione delle tabelle esterne

Inizializza le tabelle straniere necessarie al wrapper dei dati stranieri.

/opt/stablenet-fdw/init-foreign-tables.sh -h <host> -p <port> -d <database> -U <user> -o <owner>

Ad esempio.

/opt/stablenet-fdw/init-foreign-tables.sh -U postgres -h localhost -p 5432 -d infosim -o infosim

Questo comando deve essere eseguito dopo ogni aggiornamento di eranger-stablenet-fdw per ottenere nuove definizioni di tabelle.

Verifica della connessione

psql -h localhost -p 5432 -U infosim -d infosim -c "SELECT * from stablenet.stablenet_info;"

Questo comando dovrebbe restituire il numero di dispositivi nell'istanza StableNet® connessa.

Aggregazione dei dati

Inizializzazione dei dati aggregati

Inizializza l'ipertabella Timescale necessaria per i dati metrici aggregati.

/opt/stablenet-fdw/init-aggregated-data.sh -h <host> -p <port> -d <database> -U <user> -o <owner> \
-i <interval> [-m <metric_keys>] [-f <tag_filter>] [-r <retention>]

-m Elenco separato da virgole di chiavi metriche da pre-aggregare. Può essere omesso per precaricare i dati di tutte le metriche, ma potrebbe richiedere molto tempo. Ad esempio "SNMP_1,SNMP_2,SNMP_3"

-i Intervallo per precaricare i dati. es. 6 months, 1 week, 5 days

-f Tag filter per filtrare le misurazioni, ad es. "'Device Domain' eq 'Test'"

-r Politica di conservazione dei dati, ad es. "1 year"

Inizializzazione del refresh dei dati aggregati

Crea un lavoro di TimescaleDB per aggiornare periodicamente i dati aggregati per le metriche indicate.

/opt/stablenet-fdw/init-aggregated-data-refresher.sh -h <host> -p <port> -d <database> -U <user> -o <owner> \
[-m <metric_keys>][-f <tag_filter>]

-m Elenco separato da virgole delle chiavi delle metriche da aggregare. Può essere omesso per aggiornare i dati di tutte le metriche. Ad esempio "SNMP_1,SNMP_2,SNMP_3"

-f Tag filter per filtrare le misurazioni, ad esempio "'Device Domain' eq 'Test'"

Aggiungere / rimuovere metriche

Installazione di Docker Compose

Configurazione

Aggiungere le seguenti variabili d'ambiente alla sezione eranger-postgresql services environment del file SKOOR docker-compose.yaml e impostare la variabile STABLENET_FDW_WEBSERVICE_URL su un URL host StableNet valido:

      - STABLENET_FDW_WEBSERVICE_URL=https://<StableNet host>:5443/api/1
      - STABLENET_FDW_ACCEPT_INSECURE_CERTIFICATE=false
      - STABLENET_FDW_DEFAULT_USER=myuser
      - STABLENET_FDW_DEFAULT_PASSWORD=mypass
      - STABLENET_FDW_SKOOR_AUTH_URL=http://eranger-auth-${INSTANCE_NAME}:8094

Configurazione del contenitore webservice

Il webservice deve essere in grado di comunicare con il componente eranger-auth per autenticare le richieste a StableNet. Nella sezione del servizio eranger-webservice, aggiungere la seguente variabile d'ambiente:

      - SKOOR_WEBSERVICE_auth_service_url=http://eranger-auth-${INSTANCE_NAME}:8094

Inizializzazione delle tabelle straniere

Nel contenitore in esecuzione, eseguire lo script init-database.sh per eliminare e ricreare lo schema di stablenet (attenzione: tutti gli oggetti nello schema vengono eliminati!).

Esempio con un database clienti chiamato infosim con utente infosim (impostare la variabile PGSQL_CONTAINER sul nome del contenitore eranger-postgresql):

export PGSQL_CONTAINER=eranger-postgresql-<instance>
docker exec $PGSQL_CONTAINER /opt/stablenet-fdw/init-foreign-tables.sh -h localhost \
-p 5432 -d infosim -U postgres -o infosim

Eseguire una query di dati nel dashboard per verificare il wrapper dei dati esterni:

SELECT * from stablenet.stablenet_info

Aggregazione dei dati

Inizializzazione dei dati aggregati

Inizializza l'ipertabella Timescale necessaria per i dati metrici aggregati.

docker exec $PGSQL_CONTAINER /opt/stablenet-fdw/init-aggregated-data.sh -h localhost \
-p 5432 -d infosim -U postgres -o infosim -i <interval> [-m <metric_keys>] [-f <tag_filter>] [-r <retention>]

-m Elenco separato da virgole di chiavi metriche da pre-aggregare. Può essere omesso per precaricare i dati di tutte le metriche, ma potrebbe richiedere molto tempo.

-i Intervallo per precaricare i dati, ad esempio 6 months, 1 week, 5 days

-f Tag filter per filtrare le misurazioni, ad es. "'Device Domain' eq 'Test'"

-r Politica di conservazione dei dati, ad es. "1 year"

Inizializzazione dell'aggiornamento dei dati aggregati

Crea un lavoro di TimescaleDB per aggiornare periodicamente i dati aggregati per le metriche indicate.

docker exec $PGSQL_CONTAINER /opt/stablenet-fdw/init-aggregated-data-refresher.sh -h localhost \
-p 5432 -d infosim -U postgres -o infosim [-m <metric_keys>] [-f <tag_filter>]

-m Elenco separato da virgole delle chiavi delle metriche da aggregare. Può essere omesso per aggiornare i dati di tutte le metriche. Ad esempio "SNMP_1,SNMP_2,SNMP_3"

-f Tag filter per filtrare le misure, ad esempio "'Device Domain' eq 'Test'"

Integrazione in SKOOR

L'FDW StabeleNet può essere integrato creando una nuova fonte di dati nella sezione Dati e oggetti.

image-20240313-115126.png

Dopo il salvataggio, la lampadina nella navigazione dovrebbe diventare verde.

image-20240313-120727.png

Le tabelle estranee possono essere consultate nella scheda Dati .

image-20240313-121026.png

Mentre alcune tabelle estranee possono essere ispezionate immediatamente (ad esempio stablenet_taggable_device), altre necessitano di alcuni qualificatori obbligatori e non possono essere visualizzate in anteprima. Vedere la tabella seguente per i qualificatori obbligatori.

Tabelle straniere

Nome

Campi

Qualificatori

stablenet_info

server_name TEXT
name TEXT
version TEXT
technical_version TEXT

stablenet_taggable

server_name TEXT
domain TEXT
id BIGINT
name TEXT
display_name TEXT
state TEXT
attribute_tags JSONB
custom_tags JSONB
tag_filter TEXT

domain TEXT (obbligatorio)
id BIGINT
tag_filter TEXT

stablenet_taggable_device

server_name TEXT
id BIGINT
name TEXT
display_name TEXT
state TEXT
attribute_tags JSONB
custom_tags JSONB
tag_filter TEXT

id BIGINT
tag_filter TEXT

stablenet_taggable_interface

server_name TEXT
id BIGINT
name TEXT
display_name TEXT
state TEXT
attribute_tags JSONB
custom_tags JSONB
tag_filter TEXT

id BIGINT
tag_filter TEXT

stablenet_taggable_job

server_name TEXT
id BIGINT
name TEXT
display_name TEXT
state TEXT
attribute_tags JSONB
custom_tags JSONB
tag_filter TEXT

id BIGINT
tag_filter TEXT

stablenet_taggable_link

server_name TEXT
id BIGINT
name TEXT
display_name TEXT
state TEXT
attribute_tags JSONB
custom_tags JSONB
tag_filter TEXT

id BIGINT
tag_filter TEXT

stablenet_taggable_service

server_name TEXT
id BIGINT
name TEXT
display_name TEXT
state TEXT
attribute_tags JSONB
custom_tags JSONB
tag_filter TEXT

id BIGINT
tag_filter TEXT

stablenet_taggable_agent

server_name TEXT
id BIGINT
name TEXT
display_name TEXT
state TEXT
attribute_tags JSONB
custom_tags JSONB
tag_filter TEXT

id BIGINT
tag_filter TEXT

stablenet_tag_category

server_name TEXT
domain TEXT
id BIGINT
name TEXT
description TEXT

domain TEXT (obbligatorio)
id BIGINT

stablenet_measurement

server_name TEXT
id BIGINT
name TEXT
description TEXT
tags JSONB
dest_device_id BIGINT
dest_interface_id BIGINT
agent_id BIGINT
start_time TIMESTAMPTZ
end_time TIMESTAMPTZ
state TEXT
type TEXT
template_name TEXT
permanent BOOL
payload JSONB
active BOOL
tag_filter TEXT

tag_filter TEXT
dest_device_id BIGINT

stablenet_measurement_metric

server_name TEXT
measurement_id BIGINT
data_id BIGINT
description TEXT
expected_interval INT
key TEXT
name TEXT
only_average BOOL
unit TEXT

measurement_id BIGINT

stablenet_measurement_data

server_name TEXT
measurement_id BIGINT
metric_key TEXT
metric_name TEXT
"start" TIMESTAMPTZ
"end" TIMESTAMPTZ
bucket_size INT (secondi)
"timestamp" TIMESTAMPTZ
min double precision
max double precision
avg double precision
tag_filter TEXT

measurement_id BIGINT
metric_key TEXT
"start" TIMESTAMPTZ (obbligatorio)
"end" TIMESTAMPTZ (obbligatorio)
bucket_size INT (obbligatorio)
tag_filter TEXT

Sebbene measurement_id e metric_key siano opzionali, non è consigliabile eseguire le query senza. In questo modo si leggono i dati di tutte le misurazioni e di tutte le metriche, il che potrebbe richiedere molto tempo per la lettura e appesantire il server StableNet. È consigliabile solo per intervalli di tempo molto brevi < 1h. Se sono necessarie più misure e metriche, si deve usare la tabella stablenet_measurement_data_aggregated.

Dati di misurazione aggregati

Aggregati per ora, aggiornati automaticamente ogni ora. Può essere utilizzata per eseguire query analitiche su un'ampia gamma di misurazioni e su grandi intervalli di tempo.

È fondamentalmente un'ipertabella a scala temporale(https://docs.timescale.com/ ). La dimensione dei pezzi è di 7 giorni, i pezzi vengono compressi dopo 7 giorni.

Nome

Campi

stablenet_measurement_data_aggregated

server_name TEXT
measurement_id BIGINT
metric_key TEXT
metric_name TEXT
"timestamp" TIMESTAMPTZ NOT NULL
min double precision
max double precision
avg double precision

stablenet_measurement_data_aggregated contiene solo i dati delle chiavi metriche configurate.

Precedente
UI e stili di StableNet®
Successivo
Integrazione di CashPilot