Wiki

Clone wiki

recoll / ProblemSolvingData

Gathering useful data for asking help about or reporting a Recoll issue

Once in a while it will happen that a Recoll program will either signal an error, or even crash (either the recoll graphical interface or the recollindex command line indexing command).

Reporting errors and crashes is very useful. It can help others, and it can get your own problem solved.

Any problem report should include the exact Recoll and system versions.

If at all possible, reading the following and performing part of the suggested steps will be useful. This is not a condition for obtaining help though ! If you have any problem and have a difficulty with the following, just contact the mailing list or the developers (see contacts on the Recoll site support page).

If the problem concerns indexing, and was initially found using the recoll GUI, you should try to reproduce it using the recollindex command-line indexer, which is much simpler and easier to debug.

There are then two sources of useful information to diagnose the issue: the debug log file and, possibly, in case of a crash, a stack trace.

Crash and other problem reports are of very high value to me, and I am willing to help you with any of the steps described below if it is not familiar to you. I do realize that not everybody is a programmer or a system administrator.

Obtaining information from the log file

All Recoll commands write a varying amount of information to a common log file.

All commands use the same log, and the file 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). A workaround for this issue is to let the messages go to the default stderr, and redirect this.

By default, the messages are output to stderr, and you probably don't even see them if Recoll is started from the desktop. In this case, you need to set the parameters so that output goes to a file, and the appropriate verbosity level is set. When using the command-line, you may actually prefer to redirect stderr to avoid the log-truncating issue described above.

You can set the log parameters from the GUI Indexing parameters section or by editing the ~/.recoll/recoll.conf file: set the loglevel and logfilename parameters. Ie:

loglevel = 6
logfilename = /tmp/recolltrace

The log file 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).

Then run the sequence that leads to the problem, and make a copy of the log file just after. If the log is too big, it will usually be sufficient to use the last 500 lines or so (tail -500).

Single file indexing issues

When the problem concerns, or can be reproduced with, a single file it is very cumbersome to have to run a full indexing pass to reproduce it. There are two ways around this:

  • Set up an ad hoc configuration with only the file of interest, or its parent directory:
cd
mkdir recoll-test
cd recoll-test
echo /path/to/my/file/or/its/parent/dir > recoll.conf
echo 'loglevel = 6' >> recoll.conf
echo 'logfilename = /tmp/recolltrace' >> recoll.conf
recollindex -z -c .
  • Use the -e and -i options to recollindex to erase/reindex a single file. Set up the log, then:
recollindex -e /path/to/my/file
recollindex -i /path/to/my/file

When using the second approach, you must take care that the path used is consistent with the paths listed/used in the configuration (ie: if /home is a link to /usr/home, and /usr/home/me is used in the configuration topdirs, recollindex -i /home/me/myfile will not work, you need to use recollindex -i /usr/home/me/myfile

Obtaining a stack trace

If the program actually crashes, and in order to maximize usefulness, a crash report should also include a so-called stack trace, something that indicates what the program was doing when it crashed. Getting a useful stack trace is not very difficult, but it may need a little work on your part (which will then enable me do my part of the work).

If your distribution includes a separate package for Recoll debugging symbols, it probably also has a page on its web site explaining how to use them to get a stack trace. You should follow these instructions. If there is no debugging package, you should follow the instructions below. A little familiarity with the command line will be necessary.

Compiling and installing a debugging version

  • Obtain the recoll source for the version you are using (www.recoll.org), and extract the source tree.
  • Follow the instructions for building Recoll from source with the following modifications:
    • Before running configure, edit the mk/localdefs.in file and remove the -O2 option(s).
    • When running configure, specify the standard installation location for your system as a prefix (to avoid ending up with two installed versions, which would almost certainly end in confusion). On Linux this would typically be: configure --prefix=/usr
    • When installing, arrange for the installed executables not to be stripped of debugging symbols by specifying a value for the STRIP environment variable (ie: echo or ls): sudo make install STRIP=ls

Getting a core dump

You will need to run the operation that caused the crash inside a writable directory, and tell the system that you accept core dumps. The commands need to be run in a shell inside a terminal window. Ie:

cd
ulimit -c unlimited
recoll  #(or recollindex or whatever you want to run).

Hopefuly, you will succeed in getting the command to crash, and you will get a core file. A possible approach then would be to make both the executable and the core files available to me by uploading it to a file sharing site (the core file may be quite big). You should be aware though that the core file may contain some of the data that was being indexed, which may be a privacy issue. Another approach is to generate the stack trace yourself.

Using gdb to get a stack trace

  • Install gdb if it is not already on the system.
  • Run gdb on the command that crashed and the core file (depending on the system, the core file may be named "core" or something else, like recollindex.core, or core.pid), ie: gdb /usr/bin/recollindex core
  • Inside gdb, you need to use different commands to get a stack trace for recoll and recollindex. For recollindex you can use the bt command. For recoll use: thread apply all bt full
  • Copy/paste the output to your report email :), and quit gdb ("q").

Updated