Cron Job

We recommend using a cron job to send logfile requests to the Mapp tracking server every few minutes and empty your file to keep it at a manageable size. You have two options:

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.

/**
 * @param MappIntelligenceConfig|array $config Config object or array of command line options
 * @throws MappIntelligenceCLIException Missing track ID / track domain or unsupported option
 */
$mappIntelligenceCronjob = new MappIntelligenceCronjob($config);

The constructor accepts:

• a MappIntelligenceConfig object (all configuration options), or

• an array with the options of the predefined cron job script (see below), as returned by getopt(): trackId / i, trackDomain / d, consumerType / t, config / c, filename / f, filePath / f, filePrefix / p, logLevel / l, deactivate, debug, help and version. Any other key (for example maxAttempt) throws an exception; set further options in the configuration file (config).

The exception class is MappIntelligence\Cronjob\MappIntelligenceCLIException. It is thrown if the track ID or the track domain is missing or an option is not supported. Every consumer type other than FILE_ROTATION is treated as FILE.

The cron job always sends with the consumer CURL, a batch size of 1000 requests (maxBatchSize), an unlimited queue (maxQueueSize = 0, so no request of a log file is discarded because the queue is full) and no requestInterval; the configured values of these options are not used. maxAttempt, attemptTimeout, connectionTimeout, readTimeout and forceSSL are used as configured.

run

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

• 0: All data was sent successfully, there was nothing to send, the tracking is deactivated, another run of the cron job is still sending the files, or the help / version was printed.

• 1: An error has occurred: requests could not be delivered and stay for the next run, a log file contained requests that can never be sent, a log file could not be read or removed, or the configuration / directory is invalid.

Every log file is sent with its own queue, the files are processed from the oldest to the newest. Depending on the result, the file is handled like this:

A file that was sent partially keeps only the requests that were not delivered, so the next run does not send the delivered ones again. The file is replaced atomically: the remaining requests are written into a temporary file <log file>.<random>.part first, which then replaces the log file. If the replacement fails (ERROR) or the cron job is killed in the middle of a file, the whole file is sent again by the next run. A *.part file left by an aborted replacement is never cleaned up and never sent; it can be deleted, the log file still contains all of its requests. The log files belong to the cron job alone, the web servers only write into the request logging file (FILE) or the temporary files (FILE_ROTATION).

Only one run at a time sends the files: a run holds an exclusive lock (flock) on <filename>.cronjob.lock (FILE) or <filePath><filePrefix>.cronjob.lock (FILE_ROTATION). A run that starts while another one is still sending ends right away with exit status 0 and an INFO message. The lock is released by the operating system when the process ends, also if it is killed. If the lock file cannot be created (e.g. the directory does not exist or is not writable), the run sends without a lock, so overlapping runs are not prevented in that case.

With the file consumer type FILE the request logging file is taken over by renaming it into <filename>.<timestamp>-<random>.pending (the web server continues with a new file); an empty request logging file is not taken over. Every file named <filename>.….pending is sent, so an interrupted run is continued by the next one. If the request logging file cannot be taken over, the existing *.pending files are still sent and the exit status is 1.

With FILE_ROTATION, expired temporary files (configured maxFileDuration) are renamed into log files first. Only files named <filePrefix>-<timestamp>… are taken (temporary files *.tmp and log files *.log), so the prefix Shop takes neither the files of ShopDE nor those of Shop-DE.

The web server processes and the cron job are coordinated with exclusive file locks (flock()), so no request is written into a file while it is taken over.

/**
 * @return int Status
 */
$mappIntelligenceCronjob->run();

Example

use MappIntelligence\MappIntelligenceCronjob;
use MappIntelligence\Config\MappIntelligenceConfig;
use MappIntelligence\Consumer\MappIntelligenceConsumerType;

$status = 1;
try {
    $mappIntelligenceConfig = new MappIntelligenceConfig();
    $mappIntelligenceConfig->setTrackId("111111111111111")
        ->setTrackDomain("analytics01.wt-eu02.net")
        ->setConsumerType(MappIntelligenceConsumerType::FILE_ROTATION)
        ->setFilePath("/path/to/your/log/file/")
        ->setFilePrefix("MappIntelligenceData");

    $cronjob = new MappIntelligenceCronjob($mappIntelligenceConfig);

    $status = $cronjob->run();
} catch (Exception $e) {
    fwrite(STDERR, $e->getMessage() . PHP_EOL);
}

exit($status);

Predefined Cron Job Script

This option allows you to use our predefined cronjob.php script, which is included in our repository

The script loads the Composer autoloader of a standalone checkout (./vendor/autoload.php) or of the project it is installed in (vendor/autoload.php). Configuration errors are printed to STDERR.

Example

$ php cronjob.php -i 111111111111111 -d analytics01.wt-eu02.net -t FILE_ROTATION -f /tmp/ -p MappIntelligenceData
 
$ php cronjob.php -i 111111111111111 -d analytics01.wt-eu02.net -t FILE_ROTATION -f /tmp/ -p MappIntelligenceData --debug
 
 
$ php cronjob.php -c /path/to/your/configuration/file/config.ini
 
$ php cronjob.php -c /path/to/your/configuration/file/config.ini --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:

# sends every five minutes the tracking data to the Mapp tracking serve
*/5 * * * * php ./cronjob.php -c /path/to/your/configuration/file/config.ini