Using file collection mode in Node Application Metrics

What is file collection mode?

File collection mode allows the data collected by the AppMetrics agent to be saved as a nodeappmetrics${TIMESTAMP}${PID}.hcd file on the system where the agent is running.

Why use file collection mode?

In order to receive the data collected by the AppMetrics agent, a client needs to be connected to consume the data, either using the monitor() function to get access to the data via the API, or using the Health Center Eclipse IDE client via a MQTT connection. By storing the agent data collected, it can be processed at a later date without a live connection - ideal for machines that have little to no connectivity to the outside world.

Configuring file collection mode

File collection mode is configured using a set of properties, either specified in appmetrics.properties or via the appmetrics.configure() command.

File collection properties

• appmetrics.file.collection - 'on' or 'off'

  Turns file collection on or off. The default is off.

• appmetrics.file.output.directory - directory path

  Specifies the directory location in which to store the generated nodeappmetrics${TIMESTAMP}${PID}.hcd file(s). The directory does not have to exist. The default is the current directory.

• appmetrics.file.files.to.keep - Positive integer

  Specifies the number of *.hcd files to generate before deleting the oldest one to make disk space for the next one. The default is 10.

• appmetrics.file.run.duration - Positive integer

  Specifies the number of minutes to collect data into the nodeappmetrics${TIMESTAMP}${PID}.hcd file(s), after which data collection will continue with the next hcd file, or stop.

• appmetrics.file.delay.start - Positive integer

  Sets a delayed start time, in minutes. The agent waits for this length of time before starting to collect data. The default time is 0, which specifies no delay.

• appmetrics.file.max.size - Positive integer between 5000000 and 2000000000

  Sets the maximum size, in bytes, of each output file that is created. The size must be between 5000000 (5 MB) and 2000000000 (2GB). If you set a value lower than 5 MB, the property defaults to 5 MB. If you set a value greater than 2 GB, the property is ignored. By default, this property is not set, and the maximum file size is 2GB.

• appmetrics.file.run.pause.duration - Positive integer

  Sets the time, in minutes, for the agent to pause between collections. The default value is 0, which specifies no pause.

• appmetrics.file.run.number.of.runs - Positive integer

  Sets the number of collection runs. The default value is 0, which specifies that this value has no effect and the run lasts until the application ends.

##Example code

The following code collects agent data for one minute, then outputs the hcd file. You can stop the program by pressing Return.

var util = require('util')

var agent = require('appmetrics')
agent.configure({'appmetrics.file.collection':'on',
                 'appmetrics.file.run.duration':'1',
                 'appmetrics.file.run.number.of.runs':'1'});
agent.start()
console.log('Press return key to continue')

process.stdin.on('data', function (text) {
       console.log('see you later')
       process.exit()
})

The configuration options available allow for powerful control of when, where and how often you can store data in hcd files, allowing full optimization of data collection. The following code adapts the above example to collect 5 hcd files containing 10 minutes of data each, with a 30 minute gap between collections, starting after a delay of 6 hours, storing the files in the default user's home area in a directory named 'pr54321'.

var util = require('util')

var agent = require('appmetrics')
agent.configure({'appmetrics.file.collection':'on',
                 'appmetrics.file.run.duration':'10',
                 'appmetrics.file.run.pause.duration':'30',
                 'appmetrics.file.delay.start':'360',
                 'appmetrics.file.output.directory':'/home/default/pr54321',
                 'appmetrics.file.run.number.of.runs':'5'});
agent.start()
console.log('Press return key to continue')

process.stdin.on('data', function (text) {
       console.log('see you later')
       process.exit()
})