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.

#oracle_client_lib_dir =
                                        # Path to the Oracle client library directory.
                                        # This is used to load the Oracle client library
                                        # for the Oracle database connection.
                                        # If omitted, the thin client is used which might have
                                        # problems connectiong to older Oracle databases.

#history_days = 365
                                        # Number of days the history data is loaded
                                        # from the StableNet® database.
                                        # Defaults to 365 days.

[database]

#host = localhost
                                        # Hostname of the PostgreSQL database
#port = 5432
                                        # Port of the PostgreSQL database
#database = infosim
                                        # Name of the PostgreSQL database
#user = infosim
                                        # User name of the PostgreSQL database
#password = infosim
                                        # Password of the PostgreSQL database
#schema = stablenet
                                        # Schema of the PostgreSQL database
                                        # (default: stablenet)
#measurement_data_table = stablenet_measurement_data
                                        # Name of the measurement data table
                                        # (default: stablenet_measurement_data)

[retention_days]

#raw = 1
#minutely = 1
#five_minutely = 14
#fifteen_minutely = 31 # ~1 month
#hourly = 93 # ~3 months
#daily = 365 # ~1 years
#weekly = 365 # ~1 years
#monthly = 1825 # ~5 years
#quarterly = 1825 # ~5 years
#yearly = 3650 # ~10 years

[webservice]                            # use te form werbservice_<server_id>
                                        # to configure multiple StableNet® servers
                                        # (see below).

url =
                                        # URL of StableNet® the web service
database_connection =
                                        # Connection string to the StableNet® database.
                                        # This is used for the measurement data sync.
                                        # The connection string must be in the format:
                                        # MySQL: mysql+pymysql://<user>:<password>@<host>:3306/<database>
                                        # Oracle: oracle+oracledb://<user>:<password>@<host>:1521/?service_name=<service>
                                        # Connection info can be found on the StableNet server in
                                        # /opt/stablenet/snmw/wildfly/standalone/configuration/standalone.xml (<datasources>).
                                        # It's usually a good idea to use a different user and service than the one used by StableNet.
#ping_measurement_filter =
                                        # Filter for the ping measurement (e.g. 'Device Domain' eq 'Test').
#snmp_measurement_filter =
                                        # Filter for the SNMP measurement (e.g. 'Device Domain' eq 'Test').
#snmp_indexes =
                                        # List of SNMP indexes to be used for the SNMP measurement.

#[webservice_<server_id>]               # Optional, if multiple StableNet® servers
                                        # are used. Replace <server_id> with a unique
                                        # identifier for the StableNet® server.
                                        # Only alphanumeric lowercase characters are allowed.
                                        # Please note, that every webservice section
                                        # must have a unique identifier if multiple
                                        # StableNet® servers are used. if the server_id
                                        # changes, a resync of the measurement data is needed
                                        # because the measurement ID change (<measurment_id>@<server_id>).
                                        # If you already have a webservice configured without server_id,
                                        # then it's recommended to leave the existing webservice without
                                        # server_id and add a new webservice with server_id. This avoids
                                        # a resync of the measurement data.

#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 estere 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 (Deprecata)

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 dell'aggiornamento 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 esterne

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 del refresh 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-20250423-054101.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 subito (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_id TEXT
name TEXT
version TEXT
technical_version TEXT

stablenet_taggable

server_id TEXT
domain TEXT
id TEXT
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_id TEXT
id TEXT
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_id TEXT
id TEXT
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_id TEXT
id TEXT
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_id TEXT
id TEXT
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_id TEXT
id TEXT
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_id TEXT
id TEXT
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_id TEXT
domain TEXT
id TEXT
name TEXT
description TEXT

domain TEXT (obbligatorio)
id BIGINT

stablenet_measurement

server_id TEXT
id TEXT
name TEXT
description TEXT
tags JSONB
dest_device_id TEXT
dest_interface_id TEXT
agent_id TEXT
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_id TEXT
measurement_id TEXT
data_id BIGINT
description TEXT
expected_interval INT
key TEXT
name TEXT
only_average BOOL
unit TEXT

measurement_id BIGINT

stablenet_measurement_data

server_id TEXT
measurement_id TEXT
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