How To Create Useful Bugreports for the Akonadi IMAP Resource

TL;DR

To be able to debug problems we typically need:

exact used client software versions
server type
debug output
imap traffic log

For more info see the rest.

Debug Output

To enable debug output use kdebugdialog, search for imap, and enable everything. The debug output will be logged to .xsession-errors from which you can then provide the relevant parts (watch out for private data!). It is helpful if you try to reproduce the problem with the minimal steps required, and provide us with the log of that only, in order to keep it as small and relevant as possible.

IMAP traffic log

export KIMAP_LOGFILE=/tmp/imap.log
akonadictl restart

=> will log all imap traffic to files in /tmp/imap.log*

As above, try to reproduce the problem with minimal steps to keep the logs as small as possible.

Motivation

It is likely that you ended up here because you created a bug report with a proper backtrace for the Akonadi IMAP Resource, proper steps to reproduce and still it got marked as NEEDINFO with a link to that page. Maybe it sounds unfair, but the very nature of the Akonadi IMAP resource makes it much more involving to be able to make a useful bug report for it.

One thing to keep in mind is that a backtrace, unlike for a regular software doesn't tell us much as to where the issue is. It just tells us a problem happened, and the backtrace is a symptom of it, not the underlying cause. The Akonadi IMAP resource is very data driven, so its behavior heavily depends on what the IMAP server sent to it.

Improving your bug report step by step

So, you got asked for more information regarding your bug, where to start after you already reported your backtrace and the steps to reproduce the error?

There's mainly two things we need: the IMAP server type you're using, and the IMAP traffic.

Regarding the server, just the software name and version are enough, but please try to be as precise as possible. For instance telling us I'm using "the service provided by <ISP name>" is a start but requires further investigation. On the other hand, if you can tell us that the server used is a "dovecot 1.2.15" now we're in business, that will give us a much better base to find ways to reproduce the issue.

Regarding the traffic, it requires some more technical knowledge, and will involve using a console window. If that's something you're not able to do yourself you will probably need a power user or another technical savvy person to help you.

The infrastructure we're using is able to log all the traffic between your computer and the IMAP server, it is not activated by default because of privacy concerns and to avoid filling up your disk with logs. So what we'll see here is how to activate this logging facility.

To debug that kind of cases efficiently, I'd need to be provided with some idea of the IMAP traffic which created the issue. That can be done by setting the KIMAP_LOGFILE environment variable and restarting the akonadiserver.

It is done this way, open a console and then type the following commands:

export KIMAP_LOGFILE=/tmp/imap.log
akonadictl restart

Once the Akonadi server is restarted you will see quite some debugging output from the server itself. Wait for it before trying to reproduce your bug. You can see it? Good, now open up the application you used when the bug occured and try to reproduce it.

Look at the PID of the IMAP resource which exhibits the problem (it's obviously easier for a crash, the dialog shows you the PID, or if you have only one resource). You should then have a couple of /tmp/imap.log.pid.* files. You could provide those files to the developers either by attaching the relevant log files to your bug report, or by sending them privately to the developers.

Indeed, those logs will contain some private data which you don't want to see published. In that case you would have to trust the developers with your data and send it privately to them. In any case we never log the authentication phase, so none of the developers could login in your place.

If everything else fails

For some cases, like login issues, or revising some of our interpretation of the protocol RFC even the proposed steps above might not be enough. In that case, be ready to be asked for the following actions:

Using a telnet client to issue commands directly on the server and give us the replies you got;
More radical, providing access to an account for the developers to be able to connect and

issue commands themselves.

With that we'll hopefully figure something out. ;-)