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

Helix Core Server logs

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

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

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. Each request in the Swarm logs contains the following:

• URI (Uniform Resource Identifier)

• Process ID (PID) from the system

• IP address of the system that created the request

The worker event requests contain additional details such as:

• Worker ID

• Task information

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

Logrotate

From Swarm 2021.1, Swarm package installations and upgrades install logrotate to manage your Swarm log rotation. The logrotate configuration supports Swarm installations with single and multiple Helix Core Server instances.

Logrotate is on by default and is configured to:

• Rotate your Swarm logs daily.

• Keep Swarm logs for 14 days.

The helix-swarm logrotate configuration file can be modified or disabled and is located in /etc/logrotate.d. Any changes you make will be preserved when you upgrade Swarm in the future.

Reference ID

When reference_id is set to true, every log message is appended with referenceId:<id> where <id> is a hash value based on the web request id that generated the log message. The <id> is appended to all of the log messages related to that web request for the life of the web request allowing you to follow the request in the log. This can help to diagnose which request was being processed when the log message was created. It is particularly useful when you have lots of requests updating the log because it helps you to see which request each log message relates to.

Example: when a Swarm web request starts a worker the <id> that is generated is attached to all of the log entries related to that worker for the lifetime of the worker. This enables you to see all of the events the worker processes in its lifetime. For this example the web request reference Id is "066ae44103ced2ab05c28578a36b6854":

2019-02-27T09:07:21+00:00 INFO (6): Worker 1 startup. {"referenceId":"066ae44103ced2ab05c28578a36b6854"}
2019-02-27T09:07:21+00:00 INFO (6): Worker 1 event: task.commit(3276) {"referenceId":"066ae44103ced2ab05c28578a36b6854"}
2019-02-27T09:07:21+00:00 DEBUG (7): P4 (0000000055794826000000002e2ec483) start command: help  {"referenceId":"066ae44103ced2ab05c28578a36b6854"}
 .
 .
 .
2019-02-27T09:17:16+00:00 INFO (6): Worker 1 shutdown. {"referenceId":"066ae44103ced2ab05c28578a36b6854"}

To append the referenceId:<id> to Swarm log messages, edit the SWARM_ROOT/data/config.php file to include the reference_id configurable and set it to true:

<?php
    // this block should be a peer of 'p4'
    'log' => array(
        'reference_id'  => true, // defaults to false
),

The default value is false.

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 Core Server take longer than expected to complete. These warnings can be used to diagnose performance problems in the Helix Core 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 Core 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 Laminas 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.