Activating the indexing log

In the GUI, go to

Preferences->Index configuration->Global parameters

Select a file name for Indexer log file name

For investigating an indexing issue, set 'Log verbosity level` to 2 (errors only) or 3 which will list the processed files in addition to errors.

Run the indexing operation which needs investigating, then look at the log file, especially selecting lines which begin with :2: which are the error ones.

Unix and Mac: logging to stderr to catch external commands output

Set up the indexing log as above, but enter stderr as the file name.

Run the indexer as:

recollindex > /tmp/myindexlog.txt 2>&1

Both the Recoll and external command messages will be found in the resulting file.

To investigate a real time indexer issue, it’s best to add the -D option to the real time options to prevent the process from detaching from the terminal:

recollindex -c ~/.recoll -mw 0 -D > /tmp/myindexlog.txt 2>&1

Recoll logs details

All Recoll processes print trace messages. By default these go to the standard error output, and you may not ever see them (in the case, for example, of the recoll GUI command started from the desktop interface).

Log files are the primary source of information when investigating a problem.

By default all Recoll commands (GUI, indexer, Python extension) use the same log file, which is reset every time a command is started: so it is important to make a copy right after the problem occurs (for example, do not start recoll after a recollindex crash, this would reset the log).

It is possible to set program-specific log parameters to avoid this issue (described further down).

The common log file can be configured from the GUI:

Preferences->Index Configuration->Global parameters

Set the Log file name and Log verbosity level values.

You can also directly edit $HOME/.recoll/recoll.conf (or C:/Users/[me]/AppData/Local/Recoll/recoll.conf on Windows)

Setting the name as stderr will cause messages to go to the terminal which started the command.

Useful verbosity levels go in increasing verbosity from 2 to 5. 2 will only print errors, 3 gives information like what files are added or updated, 4 is for normal problem solving and 5 can be extremely verbose.

The default setup is the following:

loglevel = 2
logfilename = stderr

This will only log errors, and print them to the terminal. For a Recoll GUI launched from some Linux desktops, the messages may go to ~/.xsession-errors.

If set to use an actual file, the log at high verbosity levels (>3) can become very big if you need a big indexing run to reproduce the problem. Choose a file system with enough space available (possibly a few gigabytes).

Log parameters for specific programs

Other parameter pairs can configure the log differently for specific Recoll programs. They are used if set, else the programs fall back to a more generic parameter:

  • idxlogfilename and idxloglevel will be used by the recollindex program in batch mode.

  • daemlogfilename and daemloglevel will be used by the real time indexer (recollindex in daemon mode). It falls back to idxlog…​, and then the common log.

  • pylogfilename and pyloglevel for the Recoll Python extension called from a Python script.