How to make us love you for your issues

Most of the time, the issues reported on github or in the mail we receive are perfectly fine, don't worry. We love to hear from you in any case, so don't take the following too seriously ;) We'd still like to give some ideas on what information you can include when you report errors for VerneMQ.

OS & Erlang version:

  • Your operating system (and version)
  • Your Erlang version, which you can see  by typing erl in a shell.

A problem statement: A precise description of what happens is the core of your problem report. Ideally, it contains a limited number of steps that can reproduce the problem. Sometimes you want to describe your problem in terms of a test scenario. The most important info for a test scenario is what your expectations are. What did you expect to happen? Most certainly your test scenario involves a couple of client/server interactions, or in MQTT's way of speaking a couple of publishes and subscribes to some topics. You help us a lot by clearly stating how you do your publishes and subscribes. For instance, mosquitto_sub -h -p 1883 -t mytopic -c -q 1 -i myuser1 is a much better statement than "I subscribed with username myuser1". We can see that you use QoS 1 and clean_session false.

Client libraries used in you test setup: If you use MQTT client libraries, please let us know which ones (Paho, or some other?).

VerneMQ configuration: Show us your configuration for a single node in _build/default/rel/vernemq/etc/vernemq.conf or at least the parts of it you think are relevant. If you'd like to have an overview on the configuration, here's a nice trick: call ./vernemq config effective. This will output quite a list of VerneMQ config values to the console.

VerneMQ cluster configuration: Whenever a problem seems related to clustering, provide at least a basic description of your cluster setup.

VerneMQ Logs: This is where you look first when all hell breaks loose. _build/default/rel/vernemq/log/error.log _build/default/rel/vernemq/log/console.log _build/default/rel/vernemq/log/crash.log What those log files contain is kind of self describing, isn't it? Show us at least those couple of lines you think are related to the issue. By the way, most of the time those log files have the following format (you might encounter small variations): <date> <time> [<level>] <PID> <prefix>: <message> Example: 2015-11-03 18:27:09.448 [error] <0.974.0> ** System running to use fully qualified hostnames ** ** Hostname panarea is illegal ** Note that Erlang's internal SASL (System Architecture Support Libraries) logging is off by default.

Screenshots, gists, command line videos We love those! You can add a screenshot to a github issue. If your problem is better pictured in one of those command line videos aka ASCII cinema fun, do one and send us a link.

Advanced Wait until we ask for crashdumps and trace output! No really…wait for it :) Your final challenge: Do all of this, but shorter! Postscriptum: Did we forget something? What is your experience in supporting an open source software project?

The VerneMQ Mission Engineers