WhatIsGoingWrong

So you have a problem

Something isn't working quite right in Foswiki and you want to figure out what's happening.

Adding debugging to the code

One way to do this is to enable additional debugging in the Foswiki code.

To do this you will need write access (via sudo or some other method) to the Foswiki code tree. For the purpose of this page, let's assume that Foswiki is installed in /tools/foswiki-1.1.9.

Using Logger::PlainFile

This is an example using the Foswiki logging tools.

There was a problem with using %SEARCH% and the $pattern token for the format parameter. To see what was is happening, track down the code that implments the search function. It is located in /tools/foswiki/1.1.9/lib/Foswiki/Search.pm.

Searching that file for pattern turns up a the _extractPattern funtion that looks like a useful candidate. That is called from formatResult.

To log to the debug log, I added

use Foswiki::Logger::PlainFile        ();

after:

use Foswiki::WebFilter                ();
use Foswiki::MetaCache                ();

near the top of Search.pm. The use should be at the top of any file before defining subroutines or variables.

Then at the start of the formatResult and _extractPattern functions, I added:

my $log = new Foswiki::Logger::PlainFile;

(Note: it is possible the choice of logger should be the same as the configure setting for {Log}{Implementation}.)

When I needed to print out current state of variables I added:

$log->log('debug', "DEBUG: ($1) - $text");

in the correct place to print the matched regular pattern expression and text that it was acting on. This resulted in output like:

| 2015-07-03T02:20:50Z debug | DEBUG: (---[+][+][+]\s+([0-9]+.?*).*) - ---+++ 2 jsjsj |

in /tools/foswiki-1.1.9./working/log/debug.log. (Path of working/log is set in configure with {Log}{Dir}.)

Using perl to print to stderr

For quick and dirty debugging if you have access to the error output files of your webserver (e.g. apache's error log), you can call:

print STDERR "some debug message\n";

Writing directly to the debug or warning logs

This may be more useful for extensions. From IRC:

(03:36:17 PM) jast: protip for logging trace messages:
    Foswiki::Func::writeWarning("log me please"); (I don't
    actually ever use debug logging, but writeDebug exists, too)
(03:40:55 PM) rouilj1: I assume that works in extensions only
    since iirc Foswiki::Func defines the function exported
    from core to extensions? [edited to correct module]
(03:49:41 PM) jast: I'm not aware of a place where this one fails
    but the way you did it doesn't
(03:50:23 PM) jast: Func is mainly meant for extensions, that's
    true... but that's mainly because Func is an API that is kept
    stable, whereas internal core functions can change more readily

Running the script outside the web server

This example doesn't require changing the Foswiki files, so may also be useful, but does require that you know how to use the perl debugger.

Using perl debugger or profiler

Also from the foswiki IRC channel:

03:14:29 PM) gac410: another trick,  if you can get the bug into the
    smallest possible topic,  you can run the 'view" from CLI to get
    the output right to the console
(03:15:34 PM) gac410: cd bin;    ./view Sandbox.SomeTopic
(03:16:07 PM) gac410: On really tough ones,  that's the way to access
    the perl debugger,  or performance profilers, like Devel::NYTProf

(where bin is /tools/foswiki-1.1.9/bin).

Note that there may be some environment variables that need to be set to use this mechanism to emulate the CGI environment.

Also, to use the perl debugger, the command should probably be:

sudo -u <web server user> perl -d ./view !Sandbox.SomeTopic

where web server user is apache, httpd or www-data depending on what os variation you are running. Foswiki commands must be run using the same user that your web server would use. This will prevent files from having their ownership changed.