DocumentationStableNet® Foreign Data Wrapper (Enveloppeur de données étrangères)
Conditions préalables
Une base de données PostgreSQL avec un utilisateur autorisé à modifier les objets de la base de données est nécessaire. Le wrapper de données étrangères doit être installé sur la même instance de serveur que le serveur de base de données.
Exemple : Créer une base de données infosim appartenant au rôle 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';"
Installation standard
Installer le RPM à partir de SKOOR Repo
dnf install eranger-stablenet-fdw
Configuration
Fichier de configuration
/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
Les options peuvent également être fournies par des variables d'environnement utilisant le préfixe STABLENET_FDW_WEBSERVICE_ et le nom de l'option en majuscules (par exemple STABLENET_FDW_WEBSERVICE_URL). Pour les paramètres de global, GLOBAL doit être omis de la clé ENV (par exemple STABLENET_FDW_DEFAULT_USER ).
url est l'URl de base du service web StableNet® API. Il se présente généralement sous la forme https://<host>:5443/api/1.
Plusieurs instances StableNet® peuvent être définies en utilisant plusieurs sections webservice avec des suffixes server_id uniques. Le server_id est utilisé comme identifiant interne pour, par exemple, obtenir la chaîne d'autorisation correspondante de SKOOR Auth. Un server_name approprié doit être défini pour identifier le serveur dans les tables étrangères et agrégées. Ceci peut également être configuré à l'aide de variables d'environnement (par exemple STABLENET_FDW_WEBSERVICE_URL_TEST, STABLENET_FDW_WEBSERVICE_SERVER_NAME_TEST).
Après un changement de configuration, le serveur PostgreSQL doit être redémarré.
systemctl restart postgresql-13
Initialisation des tables étrangères
Initialisation des tables étrangères nécessaires au wrapper de données étrangères.
/opt/stablenet-fdw/init-foreign-tables.sh -h <host> -p <port> -d <database> -U <user> -o <owner>
e.g.
/opt/stablenet-fdw/init-foreign-tables.sh -U postgres -h localhost -p 5432 -d infosim -o infosim
Cette commande doit être exécutée après chaque mise à jour de eranger-stablenet-fdw pour obtenir de nouvelles définitions de tables.
Test de la connexion
psql -h localhost -p 5432 -U infosim -d infosim -c "SELECT * from stablenet.stablenet_info;"
Cette commande devrait retourner le nombre d'appareils dans l'instance StableNet® connectée.
Agrégation de données (Déclassé)
Initialisation des données agrégées
Initialise l'hypertable Timescale nécessaire pour les données métriques agrégées.
/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 Liste séparée par des virgules de clés métriques à pré-agréger. Peut être omis pour précharger les données pour toutes les métriques, mais cela peut prendre beaucoup de temps. Par exemple "SNMP_1,SNMP_2,SNMP_3"
-i Intervalle de préchargement des données, par exemple 6 months, 1 week, 5 days
-f Filtre d'étiquettes pour filtrer les mesures, par exemple "'Device Domain' eq 'Test'"
-r Politique de conservation des données, par ex. "1 year"
Initialisation du rafraîchissement des données agrégées
Crée une tâche TimescaleDB pour mettre à jour périodiquement les données agrégées pour des mesures données.
/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 Liste séparée par des virgules de clés de mesures à agréger. Peut être omis pour rafraîchir les données pour toutes les métriques. Par exemple "SNMP_1,SNMP_2,SNMP_3"
-f Filtre d'étiquette pour filtrer les mesures, par exemple "'Device Domain' eq 'Test'"
Ajouter / supprimer des mesures
Installation de Docker Compose
Configuration
Ajoutez les variables d'environnement suivantes à la section environnement des services eranger-postgresql du fichier SKOOR docker-compose.yaml et définissez la variable STABLENET_FDW_WEBSERVICE_URL à une URL valide de l'hôte StableNet :
- 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
Configuration du conteneur de service web
Le webservice doit être capable de communiquer avec le composant eranger-auth pour authentifier les requêtes à StableNet. Dans la section du service eranger-webservice, ajoutez la variable d'environnement suivante :
- SKOOR_WEBSERVICE_auth_service_url=http://eranger-auth-${INSTANCE_NAME}:8094
Initialisation des tables étrangères
Dans le conteneur en cours d'exécution, lancer le script init-database.sh pour supprimer et recréer le schéma stablenet (attention : tous les objets du schéma sont supprimés !).
Exemple avec une base de données client nommée infosim avec l'utilisateur infosim (mettre la variable PGSQL_CONTAINER au nom du conteneur 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
Exécutez une requête de données dans le tableau de bord pour vérifier le wrapper de données étrangères :
SELECT * from stablenet.stablenet_info
Agrégation de données
Initialisation des données agrégées
Initialise l'hypertable Timescale nécessaire pour les données métriques agrégées.
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 Liste de clés métriques séparées par des virgules à pré-agréger. Peut être omis pour précharger les données de toutes les métriques, mais cela risque de prendre beaucoup de temps.
-i Intervalle de préchargement des données, par exemple 6 months, 1 week, 5 days
-f Tag filter pour filtrer les mesures, par exemple "'Device Domain' eq 'Test'"
-r Politique de conservation des données, par ex. "1 year"
Initialisation du rafraîchissement des données agrégées
Crée une tâche TimescaleDB pour mettre à jour périodiquement les données agrégées pour des mesures données.
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 Liste séparée par des virgules de clés de mesures à agréger. Peut être omis pour rafraîchir les données pour toutes les métriques. Par exemple "SNMP_1,SNMP_2,SNMP_3"
-f Filtre d'étiquette pour filtrer les mesures, par exemple "'Device Domain' eq 'Test'"
Intégration dans SKOOR
Le FDW StabeleNet peut être intégré en créant une nouvelle source de données dans la section Data & Objects.
Après avoir sauvegardé, l'ampoule dans la navigation devrait devenir verte.
Les tables étrangères peuvent être inspectées dans l'onglet Data .
Alors que certaines tables étrangères peuvent être inspectées immédiatement (par exemple stablenet_taggable_device), d'autres requièrent des qualificatifs obligatoires et ne peuvent pas être visualisées. Voir le tableau ci-dessous pour les qualificatifs obligatoires.
Tables étrangères
Nom | Champs | Qualificatifs |
|---|---|---|
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Bien que measurement_id et metric_key soient optionnels, il n'est pas recommandé d'exécuter des requêtes sans eux. En effet, les données de toutes les mesures et de toutes les métriques sont lues, ce qui peut prendre beaucoup de temps et alourdit la charge du serveur StableNet. Cela n'est conseillé que pour des périodes très courtes < 1h. Si plusieurs mesures et métriques sont nécessaires, le tableau stablenet_measurement_data_aggregated doit être utilisé.
Données de mesure agrégées
Agrégées par heure, mises à jour automatiquement toutes les heures. Peuvent être utilisées pour effectuer des requêtes analytiques sur un large éventail de mesures et sur de grandes plages de temps.
Il s'agit essentiellement d'une échelle de temps hypertable(https://docs.timescale.com/ ). La taille des blocs est de 7 jours, les blocs sont compressés après 7 jours.
Nom | Champs |
|---|---|
|
|
stablenet_measurement_data_aggregated contient uniquement des données pour les clés métriques configurées.