Reporting Problems
Reporting Problems
Checking for errors
Normally, if your proxy configuration is not doing what you intended, the first step is to use the Check utility. (See check utility). This is most useful for identifying misconfiguration problems. If IIS proxy is not proxying Plone sites the way you anticipated, you should also consult the EP troubleshooting checklist. It is easy to overlook an obvious step, and this checklist reduces the possibility of this happening.
If you want to troubleshoot your includes/excludes for example, you can use a command line version of this utility with the --show-excludes switch. (See command line version of check utility).
For more subtle problems and problems specifically about caching, you should inspect the logs directly.
What & How to Report
If reporting an issue which you suspect lies with Enfold Proxy, you should zip up the text files which reside in the Enfold Proxy directory. Sending the logs with your support request will speed up Enfold's ability to help solve your problem.
The EP configuration tool lets you generate this zip file automatically. To do this, open up the EP configuration tool and choose Support on the left panel. On the right panel will be a button Create Diagnostic Zip file. If you press this button, the zip will be created and placed onto your Windows desktop. (If the zip file was previously created, EP will overwrite it).
This zip file will contain the proxy.log, the eep.ini file, he cache.log for your proxy definition(s) and some other logs related to Windows.
Before filing an issue, you should check if the issue is known or has already been addressed in the issue collector (See How to View Known Issues).
Using Logs to diagnose
Enfold Proxy has extensive logging capability and if you are willing to take some time to understand them, they can help you to diagnose the most common problems.
Tip: Use a free log monitoring tool like Bare Tail ( http://baremetalsoft.com/baretail/ ) to view your log files in real time as it updates.
Most of the time, you use logs to make sure that caching is taking place and optimized for speed. (The check utility and EP troubleshooting checklist should be enough to troubleshoot configuration problems.
The caching topic explains how to determine what percent of items are being cached (See How to Verify Caching and Find Caching Metrics ). If all you want is to see whether items are being cached, you probably can just install HTTPHeaders and see if X-CACHE: HIT shows up.
In addition, with the September 2008 version of Enfold Proxy, the product has a new logging level called HEADERS (see below). That adds HTTP headers to the logs so you don't have to go through the rigmorale of installing browser plugins to inspect HTTP requests.
Log Levels
The "log level" can be customized so that more or less information is written to the log. The default level is WARNING, meaning that all warnings and error conditions detected by EP are written to the log.
Many issues you encounter will be detected by EP as an error, so the log level will not need to be changed - just open the log file and look for any error messages. Issues such as an invalid integer in the configuration are an obvious error, so will be written to the log. Many other problems are also obviously an error, so the logs will have their information.
However, there will sometimes be more subtle issues you need to diagnose. For example, if a remote server is not available, EP will display an error page with details of the error, but will not log a WARNING message to the log - nothing is wrong with EP in this situation, just with the remote server. In such cases, EP writes an entry to the log at level INFO. Adjusting the log level to INFO will display all such conditions - information which may be valuable in tracking down external problems.
The log level DEBUG will yield lots of information - many lines for each successful and failed request. While this information is designed to allow the developers to diagnose issues with EP, it may be of benefit to anyone trying to diagnose strange interactions in the field.
The log level is adjusted in the [proxy log] section of the config file by setting log_level to a level name (eg info) or number.
Using Logs to view Headers
The Proxy log level has a special log level called "HEADERS". If this log level is enabled, every request and response will have their headers logged, as shown below. HEADERS is between DEBUG and URLS - if you set the log level to DEBUG, you will also see HEADERS - but if you set it to URLS, INFO or greater, you do not. Obviously you shouldn't run production servers at this log level. (For an explanation about what the various cache-control and HTTP headers mean, check the Cache Headers Reference.
The HEADERS log level uses arrows to indicate the direction in which HTTP requests are being handled. (If you are using Enfold Server together with IIS and Enfold Proxy, then this diagram about how requests are handled might also be helpful).
Headers will be shown with one of 4 prefixes:
-> means the incoming request (ie, from the browser - but it has some extra 'X-' headers our filter adds before it is logged)
--> means the request we make to Zope
<-- means the response from Zope back to us
<- means our response to the client/browser.
Below is an example:
[[[Incoming client request]]] 2008-09-02 16:20:46,812|proxy|HEADERS|968|160|client request VirtualHostBase/http/localhost%3A80/Plone/VirtualHostRoot/_vh_Plone/ -> Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 -> Accept-Language: en-us,en;q=0.5 -> Connection: keep-alive ... [[[ snip some headers]]] -> User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.0.1) Gecko/2008070208 Firefox/3.0.1 -> Cookie: ASPSESSIONIDCQAQSDQB=JBBPHNGCEPOFIHMDMKJJJIEA ... [[[these are some examples of the 'extra' headers added here.]]] -> X-Request-URI: /Plone -> X-EP-Host-Section: host test -> X-EP-Secure-Port: False -> X-EP-Request-Version: HTTP/1.1 [[[Here is the request we make to zope for the item]]] 2008-09-02 16:20:46,828|proxy|HEADERS|968|160|remote request for 'VirtualHostBase/http/localhost%3A80/Plone/VirtualHostRoot/_vh_Plone/' --> 'x-ep-host-section': 'host test' --> 'via': '1.1 localhost:80' ... [[[snip lots]]] --> 'X-Forwarded-Server': 'localhost' [[[ here is the zope response]]] 2008-09-02 16:20:47,046|proxy|HEADERS|968|160|remote response 200: OK (http://localhost:8080/VirtualHostBase/http/localhost%3A80/Plone/VirtualHostRoot/_vh_Plone/) <-- Server: Zope/(Zope 2.10.5-final, python 2.4.4, win32) ZServer/1.1 Plone/3.0.6 <-- Enfold Server/4.0.0 ShellEx Server/4.0.0 ... [[[here is the response Enfold Proxy sends back to the client]]] 2008-09-02 16:20:47,046|proxy|HEADERS|968|160|client response 200: OK <- Server: Zope/(Zope 2.10.5-final, python 2.4.4, win32) ZServer/1.1 Plone/3.0.6 <- Enfold Server/4.0.0 ShellEx Server/4.0.0 <- Content-Length: 20032 <- Expires: Sat, 1 Jan 2000 00:00:00 GMT <- Content-Type: text/html;charset=utf-8 <- Content-Language: en <- Via: 1.1 localhost:80 2008-09-02 16:20:47,046|proxy|URLS|968|160|Remote response 200: OK (20032 bytes, 229.274 ms, cached=False): http://localhost:8080/VirtualHostBase/http/localhost%3A80/Plone/VirtualHostRoot/_vh_Plone/
Advanced Options
Log Filenames
You can specify any filename you choose for the logs. If the filename specified is relative, it is interpreted as relative to the application directory. If the specified directory does not exist it will be created.
If you specify the same filename for each log file without max_size and backup_count also being the same, the log file rotation process may give unexpected results.
The default filename for the cache log is logs\cache.log and for the proxy is logs\proxy.log. As these defaults are relative, the default location for the logs is a logs subdirectory under the main application directory.
Log rollover
As each log becomes full, the rollover process will create backup_count copies of the old logs. These copies have the same name as the log file, but with a number from 1 to backup_count appended.
Assuming the default backup_count of 4 and a filename of cache.log, a log rollover will cause cache.log to be renamed to cache.log.1, cache.log.1 becomes cache.log.2 and so forth. An existing cache.log.4 will be discarded. All rollovers occur in the same directory as the original log file.