@smarterservices/smarterstats

smarterstats

Description: Smarterstats is a highly flexable statistics engine, offering a three step state lifecycle, internal datastore with retain settings, external datastore plugin interface and the ability to use a different clock to timestamp.

smarterstats maintains the following data-structure

stat
	collections
		metrics
			data
			analyzers
			rules

stats: the main instance of the stats engine
collections: collections are a group of metrics all related. ex. 	all stats related to s3.
metrics: the smallest grouping of a single statistical value.
analyzer: a handeler that should make calculations or do post 	proccessing on the data.
rule: access to all collections data and can set up triggers based 	on the results of an analyzer or any other data.

example structure:

stat
	s3
		uploadSpeed
			data
				analyzers
					getAverageSpeed
					storeContentLocally
				rules
					shiftStreamSpeed
					grayScale
		downloadSpeed
			data
				analyzers
					getAverageSpeed
					storeContentLocally
				rules
					shiftStreamSpeed
					grayScale
	webClicks
		clickSpeed	
			data
				analyzers
					getAverageClickSpeed
				rules
					alertUser
							

Example of a single collection with a single metric with 1 analyzer and rule.

var stats = require('@smarterservices/smarterstats')
var stat = new stats();

var firstCollection = stat.addCollection('firstCollection', {});
var firstMetric = firstCollection.addMetric('firstMetric',{type:'array'});
firstMetric.addAnalyzer(function(data,done,dataObj) {
	console.log(data)
	done();
})
firstMetric.addRule(function(data,done,dataObj) {
	console.log(data);
	done();
}
firstMetric.addData(257);

##Stats Definition: The instance of the stats engine that provides methods to add and get collections.

####Methods: addCollection(collectionName,settings)

description: adds a collection with settings based on the collection name.

Args:

collectionName:The collection name. settings: Object containing optional settings

{
timer: {
		clock: 'can pass in a module that has a method to return time'
		functionName: name of the method in the clock module that returns time in millsec.
	} //optional
	retainSettings: {
		size:'max size of all arrays in internal collection data store. dumps oldest values'
		time:'time in seconds limit how old data in internal storage can be'
	} //optional
	dataStore:'function that is proc'ed each time data is added to collection so that you can proxy to an exernal data store. function args are (key,data)
}

---

getCollection(collectionName)

description: gets a collection that was cached internally after addCollection was called.

Args:

collectionName:name of collection to retireve

##Collections

Definition: A grouping of metrics that all relate to the same topic( I.e all metrics relationg to s3)

####Methods: addMetric('Metric name',{type:'DATATYOE'})

description: adds a metric relating to that collection.

Args:

metricName: The name of the metric (ie. uploadSpeed).

settings: Object containing settings for the metric.

type: the datatype of the metric. (array/string/number/object)

---

getMetric('Metric name')

description: returns a cached instance of a metric already created with addMetric method.

Args:

metricName:The name of the metric

---

##Metrics

Definiting: A metric is a piece of statistical information related to a key that goes through the stats lifecycle every time data is added to it. Ie uploadSpeed metric containing an array of the last 20 upload speeds.

####Methods: addAnalyzer(function(data,callback,dataStore),{});

description: adds an analyze function to be ran when data is added to this metric

Args: function: a function that give you the current data for the metric, a callback to be called when your done and the dataStore object to get all collection deta if you need to. You can use this function to run any post proccessing on addData.

settings:settings for the analyzer

---

addRule(function(data,callback,dataStore),{});

description: adds a rule function to be ran after all the metrics analyzers are finished.

Args:

function: a function that gives you all the deta for the collection, a callback to be called when your function is done and the dataStore object to store any data back into the internal datastore.

---

addData(data,tags(optional);

description:this method is called to add data to a metric. This method will work differently based on the metric defined type. Array type will push data into the metric array. All other types will overwrite the current metric data.

Args:

data: the data that will be added to the internal data object.,

tags: Object that will add tags to your externalDataStore. Optional and should only be used if you set dataStore on addCollection.

---

**Analyzer**

when calling addAnalyzer you will get a callback function with prefilled arguments.

function(data,done,dataObj)

data: the data of the current metric that addData was called on.

done: callback that needs to be called when function is done(even on sync tasks)

dataObj: the entire enternal dataStore engine so that you can store data or retireve data outside of your metric

---

**Rule** when calling addRule you will get a callback function with prefilled arguments.

function(data,done,dataObj)

data: the data of the current collection.

done: callback that needs to be called when function is done(even on sync tasks)

dataObj: the entire enternal dataStore engine so that you can store data back internally.