Module: core/loggers

This module is used to store and query the history of values logged by the system. Each address has a "log" property that defines the method of logging. There is 3 methods of logging:
  • always logs each new value when those are emitted/communicated by the address driver.
  • on_update logs new values only if the new value is not equal to the previous value known by the system. Typically in KNX, it is possible that a device periodically writes a group address with the same value.
  • every x milliseconds. The system logs the last known value cyclically. It may be used for example to log values every 15 minutes.


Structure of loggers containers


{	
	'1':{
		id: 1,
		name: 'mysql usb',
		description: 'logs mysql',
		driver: 'mysql.js', //link to the Javascript driver file used to log values.
		active: 1,
		state: 'connected',  //The state can be "disconnected", "connecting", or "connected"
		json: {  // logger driver parameters
			storage: 'usb' 
		},
		private_json: {}  // can be used by applications to store custom information
	}, ...
} 


Querying historical values

The main function of this module is loggers.query(queryObject, streamCallback). It sends a query to the system, and the results are send back over time. The streamCallback function is called multiple times as the data is being retrieved.


var query = {
	// query datetime interval : 
	
	'start' :  new Date(), // Javascript date object, or timestamp in milliseconds (epoch time)
	'end'	: ...		,  // Javascript date object, or timestamp in milliseconds (epoch time)
	
	// gateways
	
	'address' 	:  ['14/7/5', '14/7/3'], //one address identifier (address id, name, or alias), or an array of address identifiers.
	
	
	// optional parameters. it defines if the values should be aggregateed over a time period.
	// The computed aggregates are the average, min, max.
	
	'aggregate' :  '15m' 	// defines the time period. It is an integer suffixed with its time unit. 
							// s => seconds 
							// m => minutes 
							// h => hours 
							// d => day 
							// w => week 
							// o => month
							// y => year
	
	// optional pack parameters. It specifies if rows are packed or not before calling the streamCallback.
	
	'pack' : 100  //here the streamCallback (e.g. function(err,rows){...}) would return rows by packs of maximum 100 rows.	
	
}

//example of executing a query : 

loggers.query({  // returns 15 minutes aggregates(min, max, and average) for KNX address 4/7/25 
	address : '4/7/25',
	start   : new Date(), // now, 
	end	    : new Date(new Date().setDate(new Date().getDate()-1)), //yesterday
	aggregate : '15m'
}, function(err, row){
	// is called multiple times. returns each rows.
	// when the streaming has end, err 'end' is sent.
	
	if(err == 'end'){
		
	}else{
		console.log(row) // where row contains the address, timestamp, and the value or aggregated values.
	}	
})


Events emitted by the loggers module

//for gateways : 

loggers.on('loggerInserted',function(newLogger){ ... })
loggers.on('loggerUpdated',function(updatedLogger, oldLogger){ ... })
loggers.on('loggerDeleted',function(deletedLogger){ ... })
loggers.on('loggerState',function(loggerId, state){ 
	// logger numerical id
	// where state equal to 'connecting', 'connected', or 'disconnected' 
})

Methods

(static) deleteLogger(loggerKey, callback)

Deletes a logger from the system. This operation is definitive. The callback returns an error if the operation failed.
Parameters:
Name Type Description
loggerKey number/string/object Logger identifier. Either id (e.g. 1), name (e.g. "mysql usb"), or logger full object (e.g. {id:1, ...})
callback function function(err){...}

(static) getLogger(loggerKey, callback)

Returns in the callback function the desired logger object. The logger object is not updated automatically. The loggerUpdated event needs to be listened in order to get potential modifications.
Parameters:
Name Type Description
loggerKey number/string/object Logger identifier. Either id (e.g. 1), name (e.g. "mysql usb"), or logger full object (e.g. {id:1, ...})
callback function function(err, logger){...}

(static) getLoggers(callback)

Returns in the callback function all the configured system loggers. The returned loggers object is not updated. Modification events needs to be listened.
Parameters:
Name Type Description
callback function function(err, loggers){...}

(static) insertLogger(logger, callback)

Inserts a new logger in the system. The callback returns an error if the operation failed. Otherwise it returns the id of the newly inserted logger.
Parameters:
Name Type Description
logger object logger full object without id (e.g. {name:'new knx logger',description:'...', driver : 'knx',json:{...}, ...})
callback function function(err, newLoggerId){...}

(static) query(queryObject, streamCallback)

This function is used to retrieves the logs.
Parameters:
Name Type Description
queryObject object this object contains the log query "start", "end", "address", plus "aggregate" and "pack" options as described above.
streamCallback function function(err, row){...}. This callback is called multiple times as the data is being retrieved from database. When the query has completed, the error "end" is passed to the callback.

(static) startLogger(loggerKey, callback)

Starts a logger. Once started, the logger tries to connect to the field bus. The event stateLogger is fired once with 'connecting', and then once again with 'connected' if the operation succed. If the connection attempt fails, the event stateLogger 'disconnected' is fired. Which means that the process is killed and will automatically restart after a short delay in order to make new connection attempts. In the rare case when the driver process crashes due to an unexpected issue or because the machine runs out of memory ressources, it will also be restarted after a short delay.
Parameters:
Name Type Description
loggerKey number/string/object Logger identifier. Either id (e.g. 1), name (e.g. "mysql usb"), or logger object (e.g. {id:1, ...})
callback function function(err){...}

(static) stopLogger(loggerKey, callback)

Stops a logger. The driver process is killed and stateLogger 'disconnected' is fired.
Parameters:
Name Type Description
loggerKey number/string/object Logger identifier. Either id (e.g. 1), name (e.g. "mysql usb"), or logger object (e.g. {id:1, ...})
callback function function(err){...}

(static) updateLogger(logger, callback)

Updates a logger. The callback returns an error if the operation failed.
Parameters:
Name Type Description
logger object logger object. It does not need to be full (e.g. {id:1, description : 'my new description'} updates only the description of the logger)
callback function function(err){...}