Logging

Helix Swarm is a web application, so there are several types of logging involved during the course of Swarm's normal operations.

Web server logging

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: https://httpd.apache.org/docs/2.2/logs.html

Helix Core Server logs

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

For more information, see Configuring logging and Auditing user file access in the Helix Core Server Administrator Guide: Fundamentals.

Swarm logs

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:

Priority	Description
0	Emergency: a message about a system instability
1	Alert: a message about a required immediate action
2	Critical: a message about a critical condition
3	Error: a message about an error
4	Warning: a message about a warning condition
5	Notice: a message about a normal but significant condition
6	Info: an informational message
7	Debug: a debugging message

Trigger Token Errors

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.

Performance logging

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

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 Server 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.