Perforce Public Knowledge Base - Perforce Chronicle Troubleshooting Guide
Reset Search



Perforce Chronicle Troubleshooting Guide

« Go Back





Where can I find information to help troubleshoot a running Chronicle installation?




You can examine log files created by your web server, Chronicle, and Perforce server to help determine the source of the problem.

What is Supported?

Web browser support: Apple Safari 5+, Google Chrome 15+, Microsoft Internet Explorer 7+, and Mozilla Firefox 3.6+ are supported on all major platforms. Other web browsers which support current standards might also work, but are not officially supported.

Perforce Server: 2011.1

PHP: 5.3+ Recommended extensions include P4PHP, APC (the Alternative PHP Cache) and Memcached for enchaned performance.

Web Sever: Apache 2.2+ Ensure mod_rewrite and mod_php4 modules are enabled. Both the module mode and CGI mode of operation are supported (SAPI, CGI and FastCGI). The Chronicle application might also work with other web server such as IIS and Lighttpd; however these web servers are not officially supported.

Web Server Operating System: Linux 2.6+



System Information in the Chronicle management toolbar provides all the important environment information for Chronicle. There is no "secure" method against modification, however a screenshot of the fields sent to support will be essential in diagnosing problems. Log into Chronicle as an Administrator and navigate to: Manage -> System Information. 



Apache web server log file location and logging level is set in the Apache configuration files but is usually under /var/log/apache2/ or similar location. Visit the Apache (for version 2.2) web site for more information on how to find and interpret log files. IIS has a separate log and error location, usually found in c:\inetpub\

Apache access or operational errors can normally be found in the Apache log files.


Chronicle uses an .htaccess (apache) or web.config (IIS) file for it's configuration. You will find configuration parameters for the appropriate mod_rewrite module within both files. If you need to add other parameters to the config file, please do not remove the existing configuration parameters.

Chronicle sites are normally set up as virtual hosts. Typically logging is configured within each virtual host configuration to more easily track down errors. The log files associated with the virtual host records web service specific errors, such as "File does not exist: /var/www/html/chronicle/favicon.ico." will exist in these locations and are defined when the virtual host is created.

When installing Chronicle, be sure your virtual host directory path matches the location of Chronicle's .htaccess file. The symptom of a path mismatch is you will be unable to get past the requirements screen when running setup.




Chronicle logs errors to (chronicle-webroot)/data/log. To increase logging navigate to the Chronicle root folder, for example /var/www/html/chronicle.

The  the application.ini found for 2011.x in <CHRONICLEROOT>/application.ini or in 2012.1 and later in <CHRONICLEROOT>/data/application.ini

You might have to rename it from application.ini.sample or something similiar for 2011.x instances. 

; Copy this file to application.ini to enable it.
; Please exercise caution when changing application settings.

phpSettings.display_startup_errors      = 0
phpSettings.display_errors              = 0

phpSettings.display_startup_errors      = 1
phpSettings.display_errors              = 1
[production] is the default Chronicle environment in the absense of an .htaccess environment setting for development mode. The above application.ini entries only apply depending upon which mode the server is running in.
To log specific actions, add below [production] or [development]

log.priority = 0-7

The access levels are accumulative, meaning that level 7 logs all actions, including those at level 3 and 6.
log.priority = 3 php errors 
log.priority = 6 web requests
log.priority = 7 Perforce commands

Application.ini should now look similar to this:

; Copy this file to application.ini to enable it. 
; Please exercise caution when changing application settings. 
phpSettings.display_startup_errors = 0 
phpSettings.display_errors = 0 
log.priority = 7 
phpSettings.display_startup_errors = 1 
phpSettings.display_errors = 1

Production vs Development Mode

Oh, to Development Mode, or Not to Development Mode. In this case, for production servers in even moderate environments we do not recommend engaging development mode except for special circumstances. It will crush even a moderately used production server by logging every transaction, disabling caching and javascript aggregation that in turn increase connections to the clients 5x or more. Only if you understand the performance implications or there is no other resort and a Technical Support Engineer is informing you to enable Development mode, then please do not do so.



If you have configured Chronicle to use an existing Perforce Server, then your server should log errors. If not, the P4LOG or -L argument must be defined when starting your standalone Perforce Server instance. If you are using log.priority=7 there is no requirement to maintain a separate P4 Server Log though it is certainly more familiar and you can compare both the Perforce Server log against the Chronicle Log at log.priority=7. Automatic RSH instances are logged in the Chronicle log, and you must utilize log.priority=7 to see Perforce commands. Because of the load generated by logging, log.priority=7 should be used sparingly, and logging level 3 is appropriate for most production environments.

See the Knowledge Base article Interpreting Server Log Files  for more information.



Site Not Responding

There are a number of reasons why a site won't respond:


  1. Host is unreachable. Standard ping or traceroute should determine routing problems. 
  2. Host resolution. Make sure the hostname or FQDN of Chronicle Site is correct. NSLOOKUP or ping domain. 
  3. Virtual Host / Virtual Server. Double check to make sure that the web server is properly configured. 
  4. Perforce Instance is unreachable/not running. Check P4PORT and 'p4 info'. 
  5. Site Cache is caching empty page. Clear cache found in CHRONICLEROOT/data/sites/<site>/cache/
  6. Firewall / Anti-virus / SElinux may be interfering with socket connections to Web or Perforce Server. Create exceptions or rules as appropriate. 



No Images or Empty Boxes in Theme Regions

This error is exposed when graphics or images do not appear in a theme's regions. This is almost always due to an inconsistency in the theme.ini setting found in when Chronicle is installed in a sub-directory or virtual directory and not a virtual host. The theme.ini for a particular theme is found here:


The output  from the regions section of a theme.ini typically looks like this:


header.1.title= Site Logo
header.1.type= widget/image
header.1.config.imageSource= remote
header.1.config.imageUrl= /sites/all/themes/default/images/logo.png
Note header.1.config.imageUrl is hard coded. This path is relative to the virtual host root. Thus, if you get this error, chances are you have not installed chronicle as its own virtual host. Do not install Chronicle in web sub-folders on Apache or virtual directories on IIS. You can also change the relative path above to include the sub directory Chronicle is running from to fix it temporarily.


Chronicle Error Page

Chronicle Errors happen for a number of reasons, but if you are getting a Chronicle error it is not a bad thing. It indicates that the Chronicle site is up and running, just that it is not happy or you don't have permission to do what you want to do. A screenshot of the specific error or a description of the error reported in the error will be most telling. Consult the Chronicle log and make sure that log.priority = 7 in the application.ini if the error page persists.


Setup Errors

Common setup errors are not having the optional or essential requirements:



  1. PHP 5.3 
  2. Web Server - Apache 2.2+ (GA), IIS 7.0 (later releases)
  3. URL Rewrite Module enabled - php rewrite or appropriate IIS (URL Rewrite Module v2)
  4. Deployment Package - p4chronicle.tgz or p4chronicle.exe (later releases).
  5. Data directory is writable - adjust file system permissions for web services user to write/own folder. 


Recommended (strongly):


  1. P4-PHP - included with distribution in CHRONICLEROOT/p4-bin/bin.<platform>/p4php/ Must be added to the PHP extensions folder and php.ini updated appropriately. 
  2. Operation Code Page Cache - php-apc (apache) or win.cache.dll (IIS) added as appropriate PHP extension. 


Less common setup errors are usually environmental. SELinux or AppArmor may interfere with setup steps or creating connections. If you are having issues connecting to Perforce site storage or any other odd errors, please check /var/log/messages or appropriate system/event log. Create an SElinux exception as appropriate. IPTables or Windows Firewall may also refuse socket connections, so make sure it is also properly configured to accept connections.

Adding a Site

Common problems with adding a site is that a second virtual host is not configured. While you can add a second Chronicle site, you won't be able to administer it from any other host. So before making another Chronicle site, make sure that an appropriate virtual host is created on the web server platform. Chronicle can utilize automatic RSH instances, or can re-use the same P4 Server instance. All sites will also be affected if Chronicle is upgraded or modified.


Common Error Messages

There are sometimes odd or weird error messages that pop up. They will either come up a pop-up growl, or within the log, or error-log of the site you are using.

ERR (3): Application error. Zend_Search_Lucene_Exception: fopen(/perforce/chronicle/data/sites/p4cms/search-index/segments_10): failed to open stream: Permission denied

This is usually caused by permission issues within your data directory, or the search-index application for the site. Make sure your Apache or Web server user has full permissions to the data directory. Enable permissions recursively if needed.


Permission Errors After Upgrade from 2011.2 to 2012.1

Because the underlieing security mechanism has changed any upgrades from 2011.2 to 2012.1 will require a reset of "Permissions" or the user/acl. The only problem is that you may get a "You do not have permission to access this content" even if you are going to your home page and are an Administrator. To get access to the management interface and reset the acl permissions you will need to adjust the Module.php for /Application/Sites and comment out the following:


1. Go to <CHRONICLEROOT>data/Application/Sites and edit Module.php.




* Integrate the site module with the rest of the application.


* @copyright   2011-2012 Perforce Software. All rights reserved

* @license     Please see LICENSE.txt in top-level folder of this distribution.

* @version     2012.1.PREP-TEST_ONLY/445190


class Site_Module extends P4Cms_Module_Integration



* Perform early integration work (before load).


public static function init()


// register a controller plugin to handle access/branch acl check

$front = Zend_Controller_Front::getInstance();

$front->registerPlugin(new Site_AccessBranchCheck);   <-- comment out with // at beginning.


// provide form to filter modules by keyword search.


2. Save and close file then restart Apache/Web Server.

3. Now login as an Admin user and reset your ACL from the URL window:

    http://<CHRONICLE SITE>/user/login

    http://<CHRONICLE SITE>/user/acl/reset



Troubleshooting is always about eliminating all non-dependent factors and zeroing in and narrowing the scope of the problem to a specific system or sub-system. Chronicle is no different. The three main system area's that might affect Chronicle: Web Services, Perforce Server, and Chronicle itself. If you have any issues or problems you can't seem to resolve yourself please contact Perforce Technical Support.


Related Links



Was this article helpful?



Please tell us how we can make this article more useful.

Characters Remaining: 255