Data Structures
struct	logger_properties

struct	Variable

Macros
#define	CACHE_SIZE 200000
	Maximum number of cached table ids.

#define	CONNECT_RETRY_ATTEMPTS 60
	Number of retry attempts before giving up....

#define	CONNECT_RETRY_SECONDS 60
	Seconds between trying to reconnect to server.

#define	DAY ( 24 * HOUR )
	(s) seconds in a day

#define	DEFAULT_MAX_AGE ( 90 * DAY )
	(s) Default value for the max age of variables to log

#define	DEFAULT_MAX_SIZE 1024
	(bytes) Default maximum binary data size of variables to log

#define	DEFAULT_SQL_DB "engdb"
	The default SQL database name to log to.

#define	DEFAULT_SQL_SERVER "localhost"
	The default host name / IP of the SQL server.

#define	DEFAULT_SQL_USER "loggerserver"
	The default SQL user name for the logger.

#define	dprintf if(debug) printf
	Macro for printing debug messages.

#define	ERROR_EXIT (-1)
	Exit code in case of an error.

#define	ERROR_RETURN (-1)
	Function return value in case of an error.

#define	FALSE 0
	Boolean FALSE (0) if not already defined.

#define	HOUR ( 60 * MINUTE )
	(s) seconds in an hour

#define	IDLE_STATE "IDLE"
	systemd state to report when idle.

#define	MINUTE 60
	(s) seconds in a minute

#define	SMAXPQ_DEFAULT_CONFIG "/etc/smax-postgress.cfg"
	Default configuration file name.

#define	SMAXPQ_MAJOR_VERSION 0
	API major version.

#define	SMAXPQ_MINOR_VERSION 9
	API minor version.

#define	SMAXPQ_PATCHLEVEL 0
	Integer sub version of the release.

#define	SMAXPQ_RELEASE_STRING "-devel"
	Additional release information in version, e.g. "-1", or "-rc1".

#define	SMAXPQ_VERSION_STRING

#define	SUCCESS_RETURN 0
	Function return value for successful completion.

#define	TIMESCALE "3 days"
	Default TimescaleDB timescale.

#define	TRUE 1
	Boolean TRUE (1) if not already defined.

#define	WEEK ( 7 * DAY )
	(s) seconds in a week

#define	YEAR ( 366 * DAY )
	(s) seconds in a leap year (366 days)

Functions
int	deleteVars (const char *pattern)

void	destroyVariable (Variable *u)

logger_properties *	getLogProperties (const char *id)

int	getMaxLogSize ()

int	getSampleCount (const Variable *u)

const char *	getSMAXServerAddress ()

int	getSnapshotInterval ()

const char *	getSQLAuth ()

const char *	getSQLDatabaseName ()

const char *	getSQLServerAddress ()

const char *	getSQLUserName ()

int	getUpdateInterval ()

int	initCollector ()

int	insertQueue (Variable *u)

int	isLogging (const char *id, double updateTime)

boolean	isUseHyperTables ()

int	parseConfig (const char *filename)

int	setSMAXServerAddress (const char *addr)

int	setSQLAuth (const char *passwd)

int	setSQLDatabaseName (const char *name)

int	setSQLServerAddress (const char *addr)

int	setSQLUserName (const char *name)

int	setupDB (const char name, const char passwd)

void	setUseHyperTables (boolean value)

void *	SQLThread ()

Variables
boolean	debug
	whether to show debug messages

Detailed Description

Date: Created on Mar 16, 2022

Author: Attila Kovacs

SMA-X to SQL database logger configuration and API.

Macro Definition Documentation

◆ SMAXPQ_DEFAULT_CONFIG

#define SMAXPQ_DEFAULT_CONFIG "/etc/smax-postgress.cfg"

Default configuration file name.

Chunk interval specification for hyper tables (Timescale DB)

For best performance it should be set s.t. chunks fill about 25% of the available memory.

For ~10k variables logged once per minute (assuming an average 8 bytes per variable plus table timestamp etc overheads), this may lead to ~0.5 GB per day.

The default is '3 days'

◆ SMAXPQ_VERSION_STRING

#define SMAXPQ_VERSION_STRING

The version string for this library

Function Documentation

◆ deleteVars()

int deleteVars ( const char * pattern )

Deletes variables and metadata from the SQL DB, and removes them from the master table also.

Parameters

pattern Glob variable name pattern

Returns: The number of variables deleted from the SQL DB, or -1 if there was an error (errno will indicate the type of error).

References MASTER_TABLE.

◆ destroyVariable()

void destroyVariable ( Variable * u )

Destroys a variable, freeing up the memory it occupies.

Parameters

u	Pointer to the variable.

References Variable::field, Variable::id, XField::name, and XField::value.

◆ getLogProperties()

logger_properties * getLogProperties ( const char * id )

Returns the currently configured logging properties for an SMA-X variable.

Parameters

id	The aggregate name/ID of the SMA-X variable

Returns: Pointer to the logging properties data structure, or NULL if there isn't one or if the id was NULL (errno will be set to EINVAL in case of the latter).

◆ getMaxLogSize()

int getMaxLogSize ( )

Returns the maximum byte size for automatically logged variables, in their binary storage format. For variables that are sampled at some interval

Returns: (bytes)

◆ getSampleCount()

int getSampleCount ( const Variable * u )

Returns the number of samples that should be logged into the SQL database for a given SMA-X variable, which may be different from the element count of the variable by a configured downsampling factor.

Parameters

u	Pointer to the variable's data structure

Returns: the number of samples that should be stored in the SQL database, or 0 if the argument was NULL.

References Variable::field, Variable::sampling, and xGetFieldCount().

◆ getSMAXServerAddress()

const char * getSMAXServerAddress ( )

Returns the SMA-X server host name or IP address.

Returns: the host name or IP address of the SMA-X server

See also: setSMAXServerAddress()

References SMAX_DEFAULT_HOSTNAME.

◆ getSnapshotInterval()

int getSnapshotInterval ( )

Returns the currently configured snapshot interval. Snapshots will be taken in the regular update cycle, whenever the time since the last snapshot equals or exceeds the set interval. For example, if the update interval is '2m', and the snapshot interval is '11m', then snapshots will be generated at every 6th update cycle, that is at every 12 minutes.

Returns: (s) the currently configured snapshot interval. Values <=0 indicate that snapshots are disabled.

See also: getUpdateUniterval()

◆ getSQLAuth()

const char * getSQLAuth ( )

Returns the SQL database password to use when connecting to the database.

Returns: The password to use for logging into the SQL database, or NULL to use passwordless login

See also: setSQLAuth()

◆ getSQLDatabaseName()

const char * getSQLDatabaseName ( )

Returns the SQL database to use when connecting to the database.

Returns: The database name to select for logging into the SQL server

See also: setSQLDatabaseName()

References DEFAULT_SQL_DB.

◆ getSQLServerAddress()

const char * getSQLServerAddress ( )

Returns the SQL server host name or IP address.

Returns: the host name or IP address of the SQL server

See also: setSQLServerAddress()

References DEFAULT_SQL_SERVER.

◆ getSQLUserName()

const char * getSQLUserName ( )

Returns the SQL user name to use when connecting to the database.

Returns: The username to use for logging into the SQL database

See also: setSQLUserName()

References DEFAULT_SQL_USER.

◆ getUpdateInterval()

int getUpdateInterval ( )

Returns the currently configured update interval.

Returns: (s) the currently configured snapshot interval. Values <=0 indicate that snapshots are disabled.

See also: getUpdateUniterval()

◆ initCollector()

int initCollector ( )

Initializes the SMA-X collector. It connects to SMA-X and starts a grabber thread in the background, which will be pushing data to the time-series database at regular intervals.

Returns: X_SUCCESS (0) if successful or else an error code (<0).

References CONNECT_ATTEMPTS, CONNECT_RETRY_INTERVAL, dprintf, ERROR_RETURN, FALSE, getSMAXServerAddress(), smaxConnect(), smaxSetPipelined(), smaxSetResilient(), smaxSetResilientExit(), SUCCESS_RETURN, TRUE, and X_NO_SERVICE.

◆ insertQueue()

int insertQueue ( Variable * u )

Add the variable to the queue for database insertion.

Parameters

u	Pointer to the variable data structure

Returns: SUCCESS_RETURN (0) if successful, or else ERROR_RETURN (-1; errno will indicate the type of error).

References ERROR_RETURN, Variable::next, and SUCCESS_RETURN.

◆ isLogging()

int isLogging	(	const char *	id,
		double	updateTime
	)

Checks if a given variable is to be logged into the SQL database

Parameters

id	The aggregate name/ID of the SMA-X variable
updateTime	(s) UNIX timestamp when the variable was last updated in the SMA-X database.

Returns: TRUE (1) if the variable should be logged into the SQL database, or else FALSE (0)

References logger_properties::exclude, FALSE, logger_properties::force, getLogProperties(), LOOKUP_INITIAL_CAPACITY, and TRUE.

◆ isUseHyperTables()

boolean isUseHyperTables ( )

Checks whether to use TimescaleDB hypertables. TimescaleDB is available for PostgreSQL only, so the setting will not affect other database backends.

Returns: TRUE (1) if to create hypertables for new variables, if possible, or else FALSE (0).

See also: setUseHyperTables()

◆ parseConfig()

int parseConfig ( const char * filename )

Pases settings from a specified configuration file

Parameters

filename the file name / path of the configuration to load.

Returns: 0 if successful, or else -1 (errno will indicate the type of error).

References dprintf, FALSE, MIN_AGE, MIN_SIZE, MINUTE, setSMAXServerAddress(), setSQLAuth(), setSQLDatabaseName(), setSQLServerAddress(), setSQLUserName(), TRUE, and X_SEP.

◆ setSMAXServerAddress()

int setSMAXServerAddress ( const char * addr )

Sets the SMA-X server address or IP.

Parameters

addr	The host name or IP address of the SMA-X server

Returns: 0 if successful, or else -1 if the name is NULL (errno will be set to EINVAL)

See also: getSMAXServerAddress()

◆ setSQLAuth()

int setSQLAuth ( const char * passwd )

Sets the SQL database password to use when connecting to the database.

Parameters

passwd The SQL database password to use

Returns: 0

See also: getSQLAuth(); setSQLDatabaseName(); setSQLUserName(); setSQLServerAddress()

◆ setSQLDatabaseName()

int setSQLDatabaseName ( const char * name )

Sets the SQL database name to select when connecting to the SQL server.

Parameters

name	The SQL database name

Returns: 0 if successful, or else -1 if the name is NULL (errno will be set to EINVAL)

See also: getSQLDatabaseName(); setSQLUserName(); setSQLAuth(); setSQLServerAddress()

◆ setSQLServerAddress()

int setSQLServerAddress ( const char * addr )

Sets the SQL server address or IP.

Parameters

addr	The host name or IP address of the SQL server

Returns: 0 if successful, or else -1 if the name is NULL (errno will be set to EINVAL)

See also: getSQLServerAddress(); setSQLDatabaseName(); setSQLUserName(); setSQLAuth()

◆ setSQLUserName()

int setSQLUserName ( const char * name )

Sets the SQL user name to use when connecting to the database.

Parameters

name	The SQL database user name

Returns: 0 if successful, or else -1 if the name is NULL (errno will be set to EINVAL)

See also: getSQLUserName(); setSQLDatabaseName(); setSQLAuth(); setSQLServerAddress()

◆ setupDB()

int setupDB	(	const char *	owner,
		const char *	passwd
	)

Sets up (bootstraps) a clean new database

Parameters

owner	User that will own the database (it must have privileges for creating the database)
passwd	Password for oqner

Returns: SUUCCESS_RETURN if successful, or else ERROR_RETURN.

References IDLE_STATE.

◆ setUseHyperTables()

void setUseHyperTables ( boolean value )

Sets whether to use TimescaleDB hypertables extension. TimescaleDB is available for PostgreSQL only, so the setting will not affect other database backends.

Parameters

value TRUE (non-zero) to enable TimescaleDB hypertables.

See also: isUseHyperTables()

◆ SQLThread()

void * SQLThread ( )

The main processing thread, which pulls values from the queue and inserts them into the database asynchronously. It is started up by initialize();

Returns: NULL

References CONNECT_RETRY_ATTEMPTS, destroyVariable(), ERROR_EXIT, IDLE_STATE, META_NAME_PATTERN, Variable::next, SQL_TABLE_NAME_LEN, SUCCESS_RETURN, and TRUE.

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ SMAXPQ_DEFAULT_CONFIG

◆ SMAXPQ_VERSION_STRING

Function Documentation

◆ deleteVars()

◆ destroyVariable()

◆ getLogProperties()

◆ getMaxLogSize()

◆ getSampleCount()

◆ getSMAXServerAddress()

◆ getSnapshotInterval()

◆ getSQLAuth()

◆ getSQLDatabaseName()

◆ getSQLServerAddress()

◆ getSQLUserName()

◆ getUpdateInterval()

◆ initCollector()

◆ insertQueue()

◆ isLogging()

◆ isUseHyperTables()

◆ parseConfig()

◆ setSMAXServerAddress()

◆ setSQLAuth()

◆ setSQLDatabaseName()

◆ setSQLServerAddress()

◆ setSQLUserName()

◆ setupDB()

◆ setUseHyperTables()

◆ SQLThread()