Cron Job

We recommend using a cron job which will send logfile requests to the Mapp tracking server every few minutes, and empty your file to keep it at a manageable size. There are two options:  Custom and Predefined. 

Custom Cron Job File

This option requires you to write your own cron job file and use our MappIntelligenceCronjob class.

Methods

constructor

For a complete configuration of the Mapp Intelligence Cronjob please check Configuration.

The constructor accepts a MappIntelligenceConfig or the command line arguments as an array (process.argv, see Predefined Cron Job Script below). Anything else throws an error (Unsupported config option). Without a track ID or track domain the constructor throws an error as well (Argument '-i' or alternative '--trackId' are required, Argument '-d' or alternative '--trackDomain' are required); catch it, run() is not reached then. Without filePath and filePrefix, os.tmpdir() and MappIntelligenceRequests are used.

The cron job always sends with the HTTP_CLIENT consumer and a batch size of 1000, whatever consumerType, setConsumer() and maxBatchSize of the configuration say, and with an unlimited queue and no requestInterval. maxAttempt, attemptTimeout, connectionTimeout, readTimeout, maxFileDuration and the log level are taken from the configuration.

/**
 * @param config Mapp Intelligence config or command line arguments
 * @throws Error Mapp Intelligence configuration exception
 */
const cronjob = new MappIntelligenceCronjob(config: MappIntelligenceConfig | Array<string>);

run

Send the logfile requests to the Mapp tracking server and delete your logfiles to keep it at a manageable size. Returns the following results:

• 0: All data was sent successfully, there were no log files to send, another run is still sending the files of the same file path and prefix (INFO), tracking is deactivated (setDeactivate(true) or --deactivate, logged at level INFO, nothing is sent), or --help / --version was printed.

• 1: An error has occurred:

  • a log file could not be sent completely or could not be read and is kept for the next run,

  • a log file contained requests that can never be sent,

  • a sent log file can neither be deleted nor renamed (see the table below),

  • the file path does not exist or is not writable, so the run lock cannot be created (Request log files "<filePath>" not found, level ERROR), or the log files cannot be listed,

  • the command line is invalid (an unsupported option prints the help on stderr).

A missing track ID or track domain throws in the constructor (see above); the predefined script mapp-intelligence-node prints the message on stderr and ends with exit status 1.

run() never ends the process itself. Errors are written to stderr, also without --debug (at the configured log level, default ERROR); --debug writes all messages of the log level to stdout.

How a run works:

1. Temporary files (<prefix>-*.tmp) that are older than the configured maxFileDuration (default 30 minutes) are renamed into log files (.log), logged at level INFO. This happens under the same lock (<prefix>.lock) the file consumers use while they write, so no request is written into a file at the moment it is renamed; a writer detects the rename and continues with a new file. A rename never replaces an existing file.

2. The log files (<prefix>-*.log, oldest first) are sent one after another. Only files named <prefix>-<timestamp>… are picked up, so the prefix Shop does not send the files of the prefixes ShopDE and Shop-DE. The result decides what happens with each file:

A file that could only be sent partially keeps only the requests that were not delivered (logged at level INFO), so the next run does not send the delivered ones again. The file is replaced atomically: the remaining requests are written into <file>.<random>.part first, which then replaces the log file. If the replacement fails, the whole file is sent again with the next run. If the cron job is killed in the middle of a file, the whole file is sent again with the next run; a .part file left behind by a run that was killed during the replacement is not picked up and not removed by the cron job, delete it manually.

Only one run at a time sends the files of a file path and prefix: a run holds the lock <filePath>/<filePrefix>.cronjob.lock and refreshes it every 10 seconds. A run that starts while another one is still sending (e.g. with a slow track server) ends right away with exit status 0 and an INFO message. The lock of a run that was killed is taken over after 60 seconds.

/**
 * @return Promise<number>
 */
cronjob.run();

Example

import {MappIntelligenceConfig, MappIntelligenceCronjob} from '@mapp-intelligence/node';

(async function() {
	let status = 1;
    try {
		const mappIntelligenceConfig = new MappIntelligenceConfig();
		mappIntelligenceConfig.setTrackId("111111111111111");
		mappIntelligenceConfig.setTrackDomain("analytics01.wt-eu02.net");
		mappIntelligenceConfig.setFilePath("/path/to/your/log/file/");
		mappIntelligenceConfig.setFilePrefix("MappIntelligenceData");
			
        const cronjob = new MappIntelligenceCronjob(mappIntelligenceConfig);
        status = await cronjob.run();
    } catch (e) {
        // e.g. a missing track ID
        console.error(e.message);
    }

    process.exit(status);
})();

Predefined Cron Job Script

This option allows you to use our predefined mapp-intelligence-node script, which is included in the package.

Example

$ mapp-intelligence-node -i 111111111111111 -d analytics01.wt-eu02.net -f /tmp/ -p MappIntelligenceData
 
$ mapp-intelligence-node -i 111111111111111 -d analytics01.wt-eu02.net -f /tmp/ -p MappIntelligenceData --debug
 
 
$ mapp-intelligence-node -c /path/to/your/configuration/file/config.json
 
$ mapp-intelligence-node -c /path/to/your/configuration/file/config.json --debug

Define a Cron Job

To create your crontab file, type the following command at the shell prompt crontab -e and add the following lines. cron starts the job in the home directory of the user: use absolute paths for the configuration file and the filePath, a relative path is resolved against the current working directory.

# sends every five minutes the tracking data to the Mapp tracking serve
*/5 * * * * mapp-intelligence-node -c /path/to/your/configuration/file/config.json