Swarm 2014.1: User Guide

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 Perforce service with every page request. Review the Swarm-generated requests on your Perforce service 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 data/log file. The volume of entries recorded in the log depends on the configuration stored in the 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 maximum value for the log priority is 7; higher values do not result in increased logging. The minimum value is 0, which means no logging; lower values do not result in further logging reductions.

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 data/queue/tokens directory.

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

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 Perforce service 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 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.