Bug reporting

Revision as of 18:24, 12 February 2013

General

Bugs or missing features are always possible in any software or other branches of engineering. We will try to fix the problems in Yate as soon as possible. Please note that our priorities may be different than yours...

Even if you spent time and accumulated frustration trying to fix a problem you should always make a good report of the problem. Try to make it brief, informative and correct. It never makes sense to just say "It doesn't work!" - that is not going to get problems fixed or even investigated.

You can read a great article by Simon Tatham on How to Report Bugs Effectively. If you want a second opinion please see what Google can find about it.

What to check before reporting?

Before making a bug report you should check if the problem was known before. Someone may be working on it, it may have been fixed or there may be workarounds.

• Make sure you are running a clean build of Yate, especially if using CVS. Subtle problems may be caused by partial builds. If the compiler crashed at any point you should clean everything and start building from start.
• Read the Documentation - especially the parts related to your problem.
• Verify if any other equipment or software you use is compatible with Yate.
• Check the Bug tracker for open bug reports of the problem. Please look at the closed and resolved bugs too - the problem may have been already fixed in a new release or in CVS.
• Check the List archive if the problem wasn't reported before.
• Ask our friend Google

What to include in the report

Making an usefull bug report is not difficult. You have to provide us maximum of information so we can locate the problem.

• A brief description of the problem, what you expect to happen and what you actually observe happening.
• Whether the problem appears always or is intermittent.
• Details about the hardware you are running Yate on - type, speed and number of processors, size of memory.
• The version of your operating system and/or distribution.
• Information on any firewall or NAT you may have on that computer or in the network (for VoIP protocols).
• Version of Yate, date of latest SVN update if applicable.
• Logs, preferably with the highest level of debugging. Please enable timestamping (options -Dt, -De or -Df).
• Backtraces of the stack if Yate crashes and a core dump is available.
• Ethereal packet captures or at least tcpdump logs (tcpdump -nn is usually enough) if you suspect network related problems.

Please do NOT include large log files. Also never include core files - they are useless without the executable that crashed and all its libraries and modules.

Do not use screen or telnet captures from rmanager. Some scripts and third party libraries write only to the log file and you may be missing important information if you take it from other sources. Only log file or console information is complete.

Crashes caused by memory corruptions leave useless core files (since the damage was caused earlier, typically by a different thread). If you see "glibc detected ... memory corruption" then please do not post such backtraces. The logs may provide some information about what went wrong.

NOTE!!! A backtrace is usefull only if it includes symbol information. You can compile the debug version of Yate, either by "make debug" or choosing the "Win32 Debug" configuration (in Windows).

Where to report bugs?

There are several places you can use to report bugs:

• For small problems or just to quickly ask a question you can use IRC - the #yate channel on the Freenode network (irc.freenode.net)
• More complex problems can be asked on the Mail list - the answer may be slower but more people may be able to answer.
• Finally, there's the [tracker] where you can report a problem, add notes, logs and patches and track how the report was handled.

How to create a comprehensive backtrace from a core file

Creating an useful backtrace may be tricky. Here is a formula to get plenty of information:

echo -e 'thread apply all bt\nquit' > gdb-bt-all.txt
gdb -x gdb-bt-all.txt yate coreFILENAME &> yate-bt-all.log

Replace coreFILENAME with the name of the generated core file. The yate-bt-all.log file will contain a backtrace of all threads. For best results Yate should be compiled with debug symbols. This does not hit the performance or memory usage, just increase the size of the files on disk.

Recent versions of Yate provide a readily made gdb-bt-all.txt in the tools subdirectory of sources.

If you have a core dump but Yate was compiled without symbols you can recompile it and get a proper backtrace - just be sure you don't change the source or configure options. Issuing a "make clean debug" will recreate all binaries with exactly the same addresses but with debugging information. Do not use "make ddebug" or "make xdebug" as these will change the code.

Creating core files

If Yate doesn't create core files when it crashes:

• Check that the directory Yate is started in is writable, there's where the core files are dumped
• Make sure you set something like ulimit -c unlimited or start Yate with the -C command line option
• Check if core size limits aren't restricted by the superuser, system policy or filesystem quota