Contents

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