Troubleshooting Helix Swarm
What is Helix Swarm?
Helix Swarm, or better known as "Swarm", is Perforce's Code Collaboration softwared based upon the MVC (Module, View, Controller) structure of the Zend Framework. It is a web driven, event-based system that collects events against the contents of a Perforce Server (P4D) instance, and presents those events and their results in an easy-to-use web interface that is designed to encourage collaboration and social interactions with design, development, management, or administrative teams.
What are Helix Swarm's Requirements?
Many of Swarm's problems usually come down to the initial setup, which revolves around meeting Swarm's requirements. The following requirements break down as following:
Note: Always check INSTALL.txt, found in the /readme/ directory of Swarm, for any updates to minimum and recommended requirements.
Web Browsers Supported
Google Chrome 25+ (stable)
Microsoft IE 10+ <- IE9 has limited functionality, IE 8 not supported.
Mozilla Firefox 19+
Operating System Requirements
Linux: kernel version 2.6+, both Swarm and P4D
Mac OS X: version 10.6+, both Swarm and P4D
Windows: not supported for Swarm (IIS or Windows Apache), P4D supported.
Perforce Server (P4D) Requirements
P4D release version 2010.2 or higher (2013.1+ recommended). Some functionality may not be available if not running 15.1+ or greater.
Perforce Swarm Requirements
PHP - (cross-platform HTML embedded scripting language) release version 5.3 or higher (5.4 recommended)
P4PHP - (the Perforce PHP API) release version 2013.1 or higher (included with Swarm by default)
iconv <-- not installed in all PHP package instances
APC - (a PHP accelerator, recommended)
Apache Server - release 2.2 or higher, with these modules:
mod_php5 - (allows Apache server to process PHP)
mod_rewrite - (allows Apache server to rewrite URLs on the fly)
Curl or Wget must be installed.
This might seem disastrous, but before contacting Perforce Technical Support, there are some steps you can take on your own that might allow you to resolve the issue, or at least collect some information that Perforce Technical Support will need in order to help you.
Common Errors on Initial Setup:
- Swarm will try to list the dependencies or requirements that are not being met. Meet the set of requirements that it outlines.
- Blank Web Page - there's a possibility the Web service can't write to the data directory, or an error in config.php file.
- The .htaccess file hidden in the "public" directory isn't being referenced or might be missing.
- Only see the "It Works!" apache page - make sure that the Virtual Host configuration is setup for the hostname and you are using the hostname/FQDN properly.
Common Issues & Errors
Helix Swarm will handle most common events with an error page or output, however below are some common errors or conditions that may not have a log entry.
Swarm Show Activity Page but No Reviews, Activity Streams data
This is a common issue encountered, usually on fresh or new installs and most will appear in the Swarm Log. You might notice that Perforce Swarm starts up in a web browser, but you can't see any changelists, reviews, etc. Some common items that contribute to this:
Trigger Problems ->
swarm-triggers.sh (swarm-triggers.vbs if accessing a Windows-based P4D) is installed but SWARM_HOST and SWARM_TOKEN variables are not set properly or incorrectly. Verify Trigger Token
and SWARM_HOST is correct.
Permissions -> the user named swarm, in our example, does not have sufficient Perforce permissions. The swarm configured user should have, at minimum, 'admin' permissions within the depot(s) Perforce Swarm will need to access. You (or a Perforce superuser or admin) can adjust the permissions by using the p4 protect command to edit the Perforce Protections Table. An error in the Swarm log should be indicated: "You do not have permission to perform this operation".
a Swarm Worker has not fired properly, or is queued to fire and has not completed its work. Before 2014.2 it could be due to a timeout error, however after 14.2 unless you have a LOT of initial historical P4 data to populate from integrations such as JIRA or Jenkins, then extend the defaults temporarily to allow workers to finish. More information see Worker Configuration
Cron Job ->
cron job/task using curl or wget is not hitting the server and generating workers. Make sure that the host has curl or wget installed and that the host can resolve the Swarm hostname. See "Setting up Recurring Task
". Beware of local firewalls and test that the following command works from the P4D server by checking in '/var/log/httpd/swarm.access_log' or '/var/log/apache2/swarm.access_log' on the Swarm server:
wget --quiet --output-document NUL --timeout 10 --post-data "shelve,1234" http://SWARM-HOSTNAME/queue/add/TRIGGER-TOKEN
If the wget connects to the Apache server you should see a log entry similar to:
127.0.0.1 - - [10/Feb/2017:14:19:13 +0000] "POST /queue/add/TRIGGER-TOKEN HTTP/1.1" 200 224
Previous Swarm Install Cruft Collisions ->
if you have previously installed Swarm before and do NOT wish to re-use this same key metadata, contact Perforce support. You will need to remove old Swarm keys, groups, 'swarm-*' clients and index data from the P4D server before you start using the new Swarm setup.
User Cannot Access Swarm Info / See Changelist or Review
Swarm also supports Restricted Changelists in 2014.1, so if the user does not have a protections entry to the particular changelists they will not be able to see the contents or the changelist.
Permission problem: Perforce Swarm is simply a Perforce client, and follows normal Perforce protections. If the user that is is logged in cannot see all paths, then checking the user's protections output via the p4 protects command will be your first step:
p4 -u <user> protects
This will output the level of access for that user.
Swarm Exclusion: Admins are able to excluded groups or users from seeing Swarm data. Please check in config.php (found in the ./data/ directory) that the user, or a group they belong to, has not been excluded. To obtain a listing of the groups to which a user belongs to, use the p4 groups command:
p4 groups -u <user>
If they are excluded or "ignored users", there will be an entry in config.php that looks similar to this:
'activity' => array(
'ignored_users' => array(
Swarm is not immune from standard web page errors, though it tries its best to catch these errors. However if they are not Zend events, then sometimes you will just see a blatant error page. Common webpage errors are below:
- You may see this if the Perforce Server is down, or not accessible, or can't be reached.
- You will also see this if the "swarm user" can't authenticate or there are connectivity issues that reset the TCP requests. Double check the hostname/IP and port the P4 Server is running on is properly configured in config.php.
- Make sure that the Perforce Swarm instance has a network router or connectivity to the P4 Server, and/or is able to resolve the hostname if a hostname or FQDN for the Perforce Server is used.
- Long latency or network congestion issues may cause the 30 second timeout to trigger, and a PHP error may be generated.
- You may see this error if PHP is not properly configured, or
- PHP modules are not working properly in Apache.
- This is a non-Perforce issue, generally, and looking in your system and Apache logs will probably give you a good hint as to what the problem is.
- Double check the minimum requirements have been met, though an error or requirements landing page should now trigger as of the 2013.1 or later release.
You may see this generic error if a particular page can't be rendered or found. However, this should be a rare occurence. Instead, if a particular page can't be rendered or found, you should see a specific Zend controller page page error in the Swarm Log.
You might see errors in the system or Apache error log similar to this:
May 8 12:57:07 ubuntu swarm-trigger.sh: error (7) trying to post [commit,5] to [http://swarm.fu.perforce.ca/queue/add/9FE1B31C-A319-DB21-EDCD-A480F5FA4A2B]
Double check to make sure your trigger script has the proper Trigger Token installed, as well that Curl can resolve the hostname of the P4 Swarm server - you may have to add an entry in /etc/hosts from where curl is running or DNS.
Obtaining Swarm Information
Perforce Swarm has its own logging system, which by default will be set to be relatively non-chatty. Logging levels range from 0 to 7, with 0 being no logging and 7 being the most chatty as it is a debug level. The default is 3 and is sufficient for 99% of all cases, and you may be asked to provide level 4, which logs performance data.
If you are asked by Tech Support to raise the logging level of Perforce Swarm, you will need to edit the config.php file, found in the ./data/ directory, and add the 'log' entry as below:
'p4' => array(
'port' => 'someip:someport',
'user' => 'someuser',
'password' => 'somepassword',
'log' => array(
'priority' => 7
The Swarm log is also found in the ./data/ directory. Generally the information found at this priority log is not useful to anyone except Swarm developers, so generally don't raise the logging level unless asked by a Perforce Technical Support rep.
(WARNING: Development Mode may have significant impact on Swarm's performance. Development Mode should only be used in a test environment, and not in a production environment.
To set your server to Development Mode, edit the config.php file (found in the ./data/ directory) with this entry:
'environment' => array(
'mode' => 'development'
You can embed this in-line with your other config.php entries, but only do it temporarily (ok to comment out).
Web Server Logs
Perforce Swarm should be configured as a normal Apache virtual host with access and error logs. Because the Apache webserver will put logs into virtual hosts where configured, it is recommended you re-direct them into the ./data/ directory to sit side by side with the Swarm logs, or to properly pre-pend or append swarm- to the name of the log if using default location, which is generally /var/log/apache/ or /var/log on most Linux distributions.
Perforce Swarm uses .HTACCESS, found in the /swarm/public/ directory, to overwrite website configurations, but largely for Perforce Swarm's rewrite rules. Generally, it is not necessary to touch the .HTACCESS file, unless it has been previously modified. However if something like URL rewriting is not working, you will want to make sure that the Rewrite Engine is "On", configured as an Apache module...etc.
Basically never modify the .HTACCESS file unless you clearly document what you have changed.
Perforce Server Log
Because Perforce Swarm is a valid Perforce Client, activity from Swarm will show up in the logs. Typically, there will be an automated (non-human) user that is configured to contact the Perforce Server using a temporary workspace. By default the automated user should be named 'swarm', but is dependent upon the 'user' configured in the config.php file.
A typical P4 Server log entry will look like this:
Perforce server info:
2013/04/04 10:23:01 pid 38436 swarm@~tmp.1365096181.1233.515db6f5be3bd5.81165494 10.2.0.126 [P4PHP/2013.1.MAIN/LINUX26X86_64/597731 (2012.2/585708 API)] 'user-counter -u swarm-activity:count 0'