Changes between Initial Version and Version 1 of support

Timestamp:

08/29/08 18:15:05 (2 years ago)

Author:

mgorny

Comment:

--

support

@@ +1 @@
+= Getting support =
+
+== First diagnostic ==
+When something unexpected happens (or something expected doesn't happen), you should first take a look at {{{__debug}}} window (alt-backtick). EKG2 currently doesn't have developed error handling and many errors are still reported only in this window. Many plugins log also whole transmitted and received packets there. Every byte of that data can be helpful when diagnosing problems.
+
+If EKG2 segfaults, it tries to write as much data as it can — including updating and closing logs, writing all debug data, configuration and dumping core. All of these files are written in ~/.ekg2 and have PID appended to their names (excluding corefile, which has it only on RH). This time also debug data would be very helpful, as well as corefile.
+
+It'd be also nice to note if problem can be reproduced and how, and whether it still appears in fresh SVN version (or snapshot).
+
+=== Getting backtrace ===
+Coredump itself is too big to be delivered to authors. Thus, it'll be your job to extract meaningful information from it. When reporting a bug, the most important data contained in coredump is backtrace. To read it, you'll need [http://sourceware.org/gdb/ gdb].
+
+{{{
+gdb <PATH_TO_EKG2_BINARY> <PATH_TO_CORE_FILE>
+}}}
+e.g.:
+{{{
+gdb /usr/local/bin/ekg2 ~/.ekg2/core
+}}}
+
+If provided path is correct, gdb should read symbols from few libraries and then display shell. Please note that you'd have to use exact the same binary (and plugins) as at the moment coredump was created. Else gdb won't be able to read it correctly. If everything went right, now enter:
+{{{
+bt full
+}}}
+
+Now gdb should output all functions being called at the moment segv occured, with all arguments included. If instead of it every other line says {{{No symbol table info available}}}, then you really should rebuild ekg2 with {{{CFLAGS="-O0 -ggdb"}}} and stripping disabled, and then try to reproduce the segfault.
+
+=== Using valgrind ===
+Another good method of diagnosing problems is running EKG2 under [http://valgrind.org/ valgrind] memcheck tool. In EKG2 sources 'contrib' dir there is 'vekg' script, allowing you to easily start EKG2 under valgrind:
+{{{
+contrib/vekg <EKG2_ARGS>
+}}}
+
+EKG2 will run noticeably slower and valgrind will log all errors and leaks in {{{~/.ekg2/valgrind.<DATETIME>*}}}. You will also notice that EKG2 won't segv anymore — that's because valgrind captures the segfault, allowing to log further errors.
+
+== Reporting bugs ==
+=== Trac ===
+You can report a bug using [http://bugs.ekg2.org/newticket Trac]. When describing a bug, please be as verbose as possible — especially including OS and distribution, used plugins, used librararies (and their versions) if you think they can be source of problem. Please include debuginfo output by EKG2 (please note that it can sometimes contain plaintext passwords (e.g. in GTalk), so please first remove them), backtrace, valgrind logs…
+
+=== Mailing lists ===
+Another way of reporting bugs and contacting developers is through mailing lists. More information can be found on [http://ekg2.org/contact.php contact page].
+
+=== IRC ===
+The developers reside in {{{!ekg2}}} channel on IRCnet. Some of them can also be found on {{{#ekg2}}}, Freenode.