Kurento is an Open Source Software WebRTC media server

Kurento issue tracker guidelines

Following the feedback provided by the community, we have opened an issue tracker facility where Kurento developers and issues may report bugs and problems and receive feedback from the Kurento core team. In order to make this tool useful, bug reports should provide relevant and complete diagnose information. In order to optimize efforts and time, we propose the following guidelines for bug reporting

Reporting bugs

Ok, you’ve run into something unexpected. Some kind of weird error that makes everything crumble. How should you proceed? This document represents the guidelines for reporting bugs found in Kurento Media Server, its libraries or any of the projects related and owned by Kurento, and hosted in the official github repository.

If you're new to reporting bugs, you may want to try getting help from the more experienced contributor. You can also ask for support on how to report in our Kurento Public Mailing list, or in our IRC channel (#kurento).

We would like all users to please observe these reporting guidelines, as they will help us all save time, and acquire the clarity needed to diagnose the problem quickly.

TL;DR

  • Be precise: don’t wander around and go straight to the point, describing as precisely as possible what’s happening

  • Be clear: explain how to reproduce the problem, step by step, so others can reproduce the bug

  • Be economic: provide the minimum amount of information needed to understand what’s happening

  • Be clean: report only one problem per issue so we can track individual issues

  • Be curious: has it been asked before? is it really a bug? Google is your friend!

How to report a bug

Is it really a bug?

The first thing before reporting a bug, is to really make sure it is a bug. Many of the messages from the list are not bugs: coding issues, configuration problems... In order to make sure there is indeed a bug, you can follow this checklist:

  • Read the documentation: If the answer is in the documentation, the answer will be “Read the documentation”... one mail round wasted
  • Webrtc is working in your target browser? you can check that here

  • Is it working on a different browser

  • If you are using TURN/STUN, make sure it is working using this page

  • Is there a tutorial that does exactly what you are trying to do? Check out the code from github, run it in your machine and see what happens. Those tutorials are tested in our CI environment, so you can be quite certain they are in good shape

  • Check your pipeline. Make a drawing if you need to, but make sure everything is connected the way it should

  • Check the configuration loaded in your KMS is what it should be. This can be seen in the first 100 lines of your KMS logs. If it’s not, change it and see if the problem is solved

  • Read the logs, they are normally quite interesting. Sometimes building tools are just not configured correctly or others have reported the same error. Client logs, server logs, build tool logs… For all of those, Google is your friend!

  • Check that you are running the same version of client libraries and KMS. While minor versions are compatible, different major versions aren’t

Ok, it’s a bug. What now?

First of all, don’t panic! There is still a small work to be done before reporting the bug.

  • If it’s an installation issue, don’t touch anything! Normally when this happens, we tend to do random things that could only make things worse

  • Choose a bug header that fits the problem

    • Bad: “I can’t see video. Help!”

    • Bettter: “KMS 6.1.1-dev is not showing loopback video in magic-mirror tutorial -FF40”

    • Best: “KMS 6.1.1-dev, magic-mirror-tutorial 6.1.1-SNAPSHOT, Mac OS X FF40 -- Can’t see loopback video”

  • Provide a good description of the problem, with the minimum relevant amount of information to reproduce and diagnose the bug

    • What steps will reproduce the problem?

    • What is the expected output?

    • What happens instead?

    • What are the specific versions of

      • KMS

        • kurento-media-server -v

        • dpkg -l | egrep -i "kurento|gstreamer|nice"

        • Service configuration in /etc/default/kurento-media-server

        • Config file in /etc/kurento/kurento.conf.json

      • Client libraries. Stating the flavour (NodeJS, JavaScript, Java or homebrewed) it’s a plus, so we don’t have to ask that later

      • Operating system where the client is running

      • Browser (type and version). If Chrome:

        • chrome://webrtc-internals both of sender and receiver as PDF

        • setLocalDescription

        • setRemoteDescription

        • Stats graphs for bweforvideo

        • Stats graphs for ssrc_*

    • How is the system deployed? Are KMS and client in the same network? Are you using TURN/STUN?

    • What does your pipeline look like?

  • If you can provide a test application, please do so. A pointer to a github repo is very welcome, as it will put us both in the same path. This doesn’t mean that we are going to debug your code, as there are many thing in there that are business-logic of your application

  • Provide the logs if they are relevant (i.e. 99% of the time)

For some specific type of bugs, there is some more information that you can provide

  • If the bug was recently introduced, finding a regression window can help identify the cause of the bug.

  • If the bug involves a media server crash, providing core dumps will be of great help

  • If you are reporting slowness or high resource consumption, please provide a profile of the system, along with the specs of the machine KMS and clients are running. It’s not the same having 20 clients in one Chrome instance, than having them in different instances on different machines.

  • If you are reporting a WebRTC bug, please provide WebRTC internals stats

    • Chrome: chrome://webrtc-internals

    • Firefox: about:webrtc

So, how should a bug report look like?

  • Summary: How would you describe the bug in less than 60 characters?

  • Version: select the earliest Version with what the problem can be reproduced

  • OS: On which operating system (OS) did you find it?

  • Description: The details of your problem report, including:

    • Overview

    • Build Id

  • Steps to Reproduce

  • Actual Results

  • Expected Results