Debugging

If your site does not work as expected, debug output can provide valuable details about the behavior of the FIT Server.

Configuration

To get debug output, you first have to enable debugging in the fit.ini configuration file.

To allow debugging from certain IP addresses only, specify one or more regular expressions against which the IP address of the client is checked. Separate multiple expressions by spaces, for example

FIT_ALLOW_DEBUG_LOGGING = true
FIT_DEBUG_LOGGING_WHITELIST = "#^93\.184\.216\.\d{1,3}$# /^192\.168\.\d{1,3}\.\d{1,3}$/"

Clients not included in the FIT_DEBUG_LOGGING_WHITELIST may be authorized to access debug information as well. Just specify a user name and a password for HTTP authentication and share those credentials with anyone who needs access, for example

FIT_ALLOW_DEBUG_LOGGING = true
FIT_DEBUG_AUTH_USER = "FIT-debug"
FIT_DEBUG_AUTH_PASSWORD = "5eCr3t-P4ssW0rD"

Authorized clients may now control debug output by setting the URL Mark d (see below).

Not restricting debug by any means and therefore allowing anyone to debug is usually not a good idea. The debug output may contain potentially sensitive information. Activating debug output noticeably decreases system performance as large amounts of data are generated and – when using the errorlog target – will be written to disk.

Therefore, on production systems, you should enable debugging only as a last resort. Ensure disabling it when you no longer need it.

However, general debugging might come in handy if you are operating a FIT server in a controlled and trusted environment:

FIT_ALLOW_DEBUG_LOGGING = true

The FIT DevBox uses this setting to allow easy debuggability, because it is only accessible from the host machine.

Usage

Given your configuration allows you to request debug output, you can activate it with the URL Mark d=<target>-<channel>-<level> in the FIT URL, for example:

http://fit.example.com/project/site;d=pageend-request-info/index.html

<target> defines where the debug output is sent to:

  • pageend: Output at the end of the page. Recommended, as it does not break anything and the page is formatted nicely.
  • page: Immediate output on the page. This will probably break your page, as the HTML code is cluttered with debug. Also, redirects and other headers cannot be sent.
  • pagejs: Output via JavaScript debug console. Recommended, when debugging AJAX communication as PPL.
  • pagejson: Uses a JSONP-like interface to call the JavaScript function fit.debug(json) if defined. You can use it to write your own debug viewer.
  • errorlog: Writes debug output to /var/log/fit14/fit_engine.log. This is not intended to be used on production systems as it quickly generates lots of data.

The <channel> is used to filter the output to one or more desired topics. Think of it as tags. Possible values are, among others, request, flow, config, time and _all_. The latter disables all filtering. To figure out all possibilities, look for the main channel of each message enclosed in square brackets (e.g. [config]) in the pageend debug output.

The <level> indicates the level of detail of the output. Allowed values are error, warning, info, debug and verbose.

If necessary, you can also enable the debug output without using the URL Mark d=. On a test system, for example, it could be useful to enable permanent debug output by setting FIT_DEFAULT_ENGINE_DEBUG appropriately:

FIT_DEFAULT_ENGINE_DEBUG = "errorlog-_all_-warning"

Reading the Debug Output

Context and Configuration

If you have the FIT DevBox up and running, try out debugging with the following link:

http://local14.sevenval-fit.com/;d=pageend-config-debug/

The green boxes give you information about the request context like the FIT version, installed extensions, project, site etc. This is a good starting point for investigations, if you are not sure whether your setup is correct.

The URL Config is of special interest, because this is the glue between the domain configuration and the current site. Check here if links are rewritten unexpectedly or if switching the protocol (e.g. to HTTPS) does not work. Maybe there is no HTTPS URL configured in the system? Also, the printed Client Protocol should match the URL scheme in your browser (e.g. https). Maybe the load balancer sends SSL offloaded traffic to FIT’s HTTP port? Maybe a required X-Forwarded-Proto header is missing or has an invalid value? The SSL mode field can give you a hint about the current VHost configuration.

The config channel reflects your site’s config files. It lists all config files and directories and whether they are present and syntactically correct. Check here if you have the feeling, that your files are not read. Maybe you have misspelled the name? Or XIncludes have failed? Or the XML did not parse?