wiki:debugging

Version 6 (modified by octo, 11 years ago) (diff)

--

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

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

Error: Failed to load processor ShellExample
No macro or processor named 'ShellExample' found

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.

Using the built-in logging

This feature works with from version 0.4 onward.

  • 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"
  • Uncheck everything except "LogicMail"
  • Return to the "Event Log" screen.
  • Go to the menu, and select "Clear Log", and confirm.
  • Return to the main BB screen
  • Start LogicMail
  • Go to the menu, select "Config", and enable "Connection debugging".
  • Now select your account, and do whatever caused the issue you were having.
  • Once done, go back to the menu, then do the "Config" screen, and disable "Connection debugging".
  • Quit out of LogicMail.
  • Press: Alt-lglg
  • Go to the menu, and select "Copy Day's Contents", and select "Filtered"
  • Return to the BB main screen.
  • Now, 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.

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.