wiki:debugging

Debugging

Writing a bug report

If you run into an "Unknown error" in LogicMail, chances are that you have found a bug. However, simply telling me about it really won't do any good. If you want to write a useful bug report, you first need to collect the following information:

  • What you did that triggered the error
  • What mail server software you were connecting to (i.e. Cyrus, Courier, Dovecot, Exchange, etc.)
  • What was happening in the network conversation between LogicMail and the mail server when the error occurred
    • You can find this out by packet sniffing the connection between your BlackBerry, or a simulator, and your mail server.
    • You can also find this out by simulating the same commands LogicMail uses, using something like telnet

Using the built-in logging

This feature works with from version 0.4 onward. On most BlackBerry devices, you can access the system event log by pressing Alt-lglg while on the home screen. On the BlackBerry Storm, follow the instructions described  here. If those don't work, Corey Gilmore wrote a very nice  helper application to bring up the event log.

Configure the Event Logger

  • Press: Alt-lglg (the Event Log screen should appear)
  • Go to the menu, and select "Options"
  • Change the "Min log level" option to "Debug Info"
  • Click the Menu button and select "Hide all types" to uncheck everything
  • Now find and check the following items:
    • Java Exception
    • LogicMail
    • net.rim.networkapi (if available)
    • net.rim.tcp (if available)
  • Return to the "Event Log" screen.
  • Go to the menu, and select "Clear Log", and confirm.
  • Return to the main BB screen

Use LogicMail to reproduce the issue

  • Start LogicMail
  • Go to the menu, select "Configuration", scroll to the bottom, and enable "Connection debugging". (Note: Connection debugging only helps if the issue is a protocol error. It won't be useful for connection problems.)
  • Now select your account, and do whatever caused the issue you were having.
  • Once done, if you enabled connection debugging above, go back to the "Configuration" screen and disable "Connection debugging".
  • Quit out of LogicMail.

Capture the log

  • Press: Alt-lglg
  • Go to the menu, and select "Copy Day's Contents", and select "Filtered"
  • Return to the BB main screen.
  • Paste the log contents somewhere that you can access from off of your device. There are a few options for this, but the most direct is a Task item:
    • Go to "Tasks", create a new task, and paste the event log data into the "Notes" section at the bottom of the screen. (surprisingly, this can hold a lot more text than a MemoPad note.)
    • Finally, sync this Task item to your PC, censor anything you don't want me to see (i.e., replace names and passwords with dummy characters), and either send the log to me, or attach it to a bug ticket.

Notes on providing logs

  • When you censor the log text, please don't change the length or existence of special characters in the data. Please leave in any and all spaces, punctuation, quotes, newlines, etc. Any of these things could be the cause of the error, and if I cannot reproduce the issue by running pieces of LogicMail on data in the log, I cannot fix it.
  • Before sending me a log, please actually try to read it. I make the logs quite verbose, and it should be obvious whether or not the log actually contains any sort of useful error message. If the log just says the application started, loaded some local folders, then "Unable to open connection", the log probably does not actually contain any useful information.
  • When posting a log to this website, please use WikiFormatting so it is displayed correctly. For a log dump, this usually means enclosing the log text like this:
      {{{
      d LogicMail - MaildirFolder.open()
      Opening: file:///SDCard/BlackBerry/logicmail/local/Drafts - 7/2 18:23:17
      i LogicMail - Application startup
      Date: Sat Jul 02 18:23:16 Europe/Brussels 2011
      Name: LogicMail
      Version: 2.0.0.282
      Platform: 9700 5.0.0.586
      - 7/2 18:23:16
      }}}
    

Capturing IMAP traffic

Using something like telnet (or an SSL-enabled telnet), you can connect to your mail server and send the same commands that program like LogicMail would. Below are some examples of common operations that could be used to produce bug reports for LogicMail issues.

When you send in your transcript in a bug report, you probably want to sanitize the information so you aren't posting anything sensitive or personal. However, please don't change the length or existence of special characters in the data. Please leave in any and all spaces, punctuation, quotes, newlines, etc. Any of these things could be the cause of the error, and if I cannot reproduce the issue by running pieces of LogicMail on data in the transcript, I cannot fix it.

View messages in a mailbox

$ telnet mail.example.org 143
Trying 192.168.20.10...
Connected to mail.example.org.
Escape character is '^]'.
* OK mail.example.org Cyrus IMAP4 v2.3.0 server ready
A1 CAPABILITY
* CAPABILITY IMAP4 IMAP4rev1 ACL QUOTA LITERAL+ MAILBOX-REFERRALS NAMESPACE UIDPLUS ID NO_ATOMIC_RENAME UNSELECT CHILDREN MULTIAPPEND BINARY SORT THREAD=ORDEREDSUBJECT THREAD=REFERENCES ANNOTATEMORE CATENATE IDLE STARTTLS AUTH=GSSAPI SASL-IR URLAUTH
A1 OK Unknown code imap 54
A2 LOGIN testuser testpass
A2 OK User logged in
A3 SELECT "INBOX"
* FLAGS (\Answered \Flagged \Draft \Deleted \Seen)
* OK [PERMANENTFLAGS (\Answered \Flagged \Draft \Deleted \Seen \*)]
* 20 EXISTS
* 0 RECENT
* OK [UNSEEN 14]
* OK [UIDVALIDITY 1084720106]
* OK [UIDNEXT 21]
A3 OK [READ-WRITE] Unknown code imap 54
A4 FETCH 19:20 (FLAGS ENVELOPE)
* 19 FETCH (FLAGS (\Seen) ENVELOPE ("Sat, 17 Mar 2007 15:51:48 -0400" {19}
[blah] "quote test" (("Derek Konigsberg" NIL "octo" "logicprobe.org")) (("Derek Konigsberg" NIL "octo" "logicprobe.org")) (("Derek Konigsberg" NIL "octo" "logicprobe.org")) ((NIL NIL "foo" "genericfoo.org")) NIL NIL NIL "<200703171551.48597.octo@logicprobe.org>"))
* 20 FETCH (FLAGS (\Seen) ENVELOPE ("Sun, 18 Mar 2007 09:04:29 -0700" {23}
[list] "this is a test" (("Bill Smith" NIL "bsmith" "XXXX")) (("Bill Smith" NIL "bsmith" "XXXX")) (("Bill Smith" NIL "bsmith" "XXXX")) ((NIL NIL "bsmith" "XXXXXXXX")) NIL NIL NIL "<45FD630D.1040808@XXXXX>"))
A4 OK Unknown code imap 54 (0.000 sec)
A5 LOGOUT
* BYE Unknown code imap 53
A5 OK Unknown code imap 54
Connection to mail.example.org closed by foreign host.

The important things to note in this transcript are:

  • Each command is prefixed with a unique identifier. In this case, I'm just using a letter with an incrementing number. It really doesn't matter what you use. The reason for this is so that replies can be matched up with the commands that requested them.
  • Each command is concluded when the server sends back its identifier along with an "OK"
  • The "LOGIN" command has the username and password after it. Surround them with quotes if necessary.
  • The line ending with "EXISTS" shows you the number of messages in the mailbox.
  • The "FETCH" command contains the range of messages to retrieve information for. In this case, its messages 19 through 20.