See www.zabbix.com for the official Zabbix site.

Docs/bug reporting guidelines

From Zabbix.org
Jump to: navigation, search

Zabbix bug reporting guidelines

Zabbix issue tracker can be found at https://support.zabbix.com .

General guidelines

Zabbix issue tracker has two projects:

  • ZBX - only for bug reports
  • ZBXNEXT - only for feature requests

General info

Zabbix ID issue states (abandoned, not used anymore)

  • RTF, Ready to fix
  • RTD, Ready to discuss
  • RTI, Ready to ... ignore
  • RTR, Ready to reproduce
  • NMR, Next Major Release

Before reporting

  • Search the issue tracker - make sure your problem isn't reported already.
  • If unsure, discuss your problem in #zabbix IRC channel on Freenode network.
  • Make sure to report problems for latest released version. Problems found in older releases might be already fixed in latest version.
  • If possible, test the problem in svn HEAD or nightly build.
  • If you have made any modifications to the Zabbix code, make sure that the problem is reproducible with vanilla (unmodified) version of Zabbix.

Reporting an issue

  • Report issues and comment in English only - it is a bit hard for Japanese users to understand Russian and vice versa.
  • Describe the problem in the issue itself - do not link to external sites (forum, pastebin sites etc) or attach files that are supposed to describe the problem. Doing otherwise might result in the information being inaccessible later, increases the burden on issue reviewers/developers and breaks the search.
  • Describe issue clearly - what exactly you did, what happened, what you expected to happen instead.
  • If you know in which version the problem appeared, add that information, or at least the last known working version & in which version it first broke.
  • Add relevant detail - if it might be connected, add things like database, operating system, PHP version and other information.
    • On the other hand, don't overload issue with unnecessary information - for example, usually it doesn't make sense to report PHP version for a Zabbix server problem.
  • If the problem is reproducible, add detailed steps. Ideally, try to reproduce in a fresh installation of Zabbix.
  • One problem - one issue. Don't put multiple problems in one issue (unless they are very small and closely related).
  • Don't add "me too" or "when will this be fixed" comments to issues - those aren't productive and only clutter the issue. Discuss issues in Zabbix forums or IRC channel. On the other hand, if the issue is unclear and hard to reproduce, it might be worth adding relevant environment details and whether problem is reproducible there.
    • If you want to show that you also suffer from a particular problem and would like to see it fixed, vote on it. Jira issue voting.png
  • Try to set reasonable labels for the issue
    • Do not repeat component information (like server or proxy) in labels
    • Label patch is used to denote issues that have a patch that proposes a solution. Other patches (like debugging, for example) should not get such a label.
  • If an issue is reported against some version, it is supposed to affect that version and all later versions, unless noted otherwise. For bugreports, it is useful to mention in comments that it is still reproducible in some later version. It is not worth mentioning that some feature is still missing or asking whether it has been implemented if the issue is still open.
Formatting

When linking to other issues, don't set manual links or paste full URLs - just include the plaintext issue key like ZBX-13 - Jira will detect it and link automatically.

Adding files

  • If you want to attach screenshots, please, attach them directly - do not include them in rtf, doc or any other files.
  • When creating screenshots, please, use PNG format (not JPEG or TIFF) - PNG fies will usually be smaller.
  • When attaching plaintext information like logfiles, use plaintext files only, do not include it in rtf, doc or any other files.
  • Don't upload screenshots to 3rd party sites, upload them to the Zabbix issue tracker. 3rd party sites might be unavailable later or they might expire uploaded images.
  • If you are adding logfiles, objdump output or similar files and they are larger than 1MB, please, compress them. Use xz, bzip2 or gzip for compression - avoid other formats. Usually xz will provide the best compression ratio.
  • If you get an error message in text, don't take a screenshot of it, copy it. It makes much easier to search issues later and allows developers to copy the message if needed.
  • If you have a proof-of-concept patch, it would be appreciated if it followed the Zabbix coding style.

Component specific guidelines

Frontend

Note: Finding out the exact revision where the problem appeared is optional, but it can greatly help developers to identify what caused it, thus getting the problem fixed faster.

For Zabbix frontend, it is rather easy to find when exactly a problem appeared (assuming it's a recent regression).

If possible, you should try the following (assuming you are testing Zabbix 1.8 branch):

Change to the webserver http document root directory, where you, hopefully, have used subdirectories for software like Zabix. Common directories include /srv/www/htdocs, /var/www/html and /var/www. Check out Zabbix frontend from svn repository:

 svn co svn://svn.zabbix.com/branches/1.8/frontends/php 1.8-branch

Copy over conf/zabbix.conf.php from your existing frontend directory over to conf subdirectory in 1.8-branch.

Now access this directory in a web browser - this is the latest development version of this branch. After the checkout finishes, you should be able to see which revision you got, for example:

 Checked out revision 24840.

Assuming the problem is still visible in this development version, you can now change to any old version (change directory to 1.8-branch directory first). For the output above, one could get the frontend as it existed 100 revisions ago:

 svn up -r 24740

Now you can check whether this version is OK.

Finding the exact revision that created the problem is a somewhat manual work, but with some experience you should be able to do that rather quickly. For example, you can narrow down the range by stepping back by 100 revisions like this until you find revision that still works OK. Then you can do smaller revision increments until you get to the problematic one. Another way to help with finding the problematic revision would be to check svn log as well. For example, you could see all changes, performed between two revisions:

 svn log -r 24740:24840

If you see that there were no changes for a half of that range, you can immediately exclude or skip that in your "revision jumping".

Once you have found the exact revision which created the problem, make sure to note that down in your bugreport.

See also more detailed instructions on using Zabbix Subversion repository.

Daemons and commandline utilities

Zabbix daemons include Zabbix server, agent and proxy.

Zabbix commandline utilities include Zabbix sender and Zabbix get.

If a Zabbix process has crashed, make sure to attach:

  • logfile portion before the crash (include the backtrace part and some lines before it)
  • compressed objdump output, produced with objdump -DSswx <binary file>

Specify whether it's a static or dynamic build.