Swarm 2017.2 Guide (August 2017)

All accesses to Swarm may be logged by the web server hosting Swarm. As web server log configuration is web server specific, refer to your web server's documentation. Since we recommend the use of Apache, more information regarding log configuration in Apache can be found here:

Swarm communicates with the associated Helix Versioning Engine for every page request. Review the Swarm-generated requests on your Helix Versioning Engine by enabling logging.

Depending on the log configuration you provide to Swarm, Swarm can log its own operations. Swarm's logs are much more helpful if you encounter problems.

Swarm stores its log data in the SWARM_ROOT/data/log file. The volume of entries recorded in the log depends on the configuration stored in the SWARM_ROOT/data/config.php file. Here is an example:

<?php
    // this block should be a peer of 'p4'
    'log' => array(
        'priority'  => 3, // 7 for max, defaults to 3
    ),

The log priority specifies the importance of the messages to be logged. When priority is set to 0 (the lowest value) only the most important messages are logged. When priority is set to 7 (the highest value) all messages, including the least important messages are logged. The default priority is 3.

The different priority levels are:

If the trigger tokens are missing or invalid, the web server error log contains a suitable error:

queue/add attempted with invalid/missing token: token used

A token is invalid when it is not formed from the characters A through Z (in upper or lowercase), 0 through 9, or a dash (-).

A token is missing when a file using the token as its name does not exist in the SWARM_ROOT/data/queue/tokens directory.

Swarm logs warnings whenever commands issued to the Helix Versioning Engine take longer than expected to complete. These warnings can be used to diagnose performance problems in the Helix Versioning Engine.

The default configuration is:

<?php
    // this block should be placed within the 'p4' block
    'slow_command_logging' => array(
        3, // commands without a specific rule have a 3-second limit
        10 => array('print', 'shelve', 'submit', 'sync', 'unshelve'),
    ),

In this configuration block, the numeric key specifies the time threshold in seconds, and the value (if present) is an array of Helix Versioning Engine commands that should use the threshold. Should a command be associated with multiple thresholds, the largest is used for that command.

In addition, Swarm automatically detects when the PHP extension xhprof is installed and collects profiling data for requests that take longer than expected. The profiling data could be helpful in diagnosing performance issues within Swarm itself, particularly when analyzed in combination with the slow command logging described above. When collected, profiling data is stored in the SWARM_ROOT/data/xhprof folder.

The default configuration is:

<?php
    // this block should be a peer of 'p4'
    'xhprof' => array(
        'slow_time'      => 3, // the threshold in seconds
        'ignored_routes' => array('download', 'imagick', 'libreoffice', 'worker'),
    ),

slow_time specifies the threshold, in seconds, that should be used to determine when a Swarm request is slow. ignored_routes is an array that specifies a list of Zend Framework route names that should not be profiled. For example, Swarm's Files module specifies that the download route should be ignored from profiling as downloads could take significantly longer than the default threshold.