A typical first task for new employees at callstats.io is to get to play with the WebRTC API. We do this, partly, to make new recruits understand the WebRTC development process, get used to the jargon related to multimedia and networking, and to better understand the pitfalls in using the WebRTC API. The last bit can sometimes be challenging, as they have to factor in the quirks of various implementations (e.g., Chrome, Firefox, Temasys plugin), even though adapter.js does some of the heavy lifting.

Karthik joined us last month and created a full featured app with screen sharing (both for Firefox and Chrome) in a week (more on his experience in an upcoming post). However, one of the issues we noticed across deployments was conference setup failure (i.e. the conference failed to start). Oftentimes, we regarded this as failure to establish connectivity, mainly due to impermissive NATs and firewalls (we found this number was around 10%). Nevertheless, we speculated that some of these failures may occur due to various other reasons including, Negotiation Failure (i.e. exchanging and setting the media and transport parameters for each participant). Figure 1 shows what errors may occur at various stages of setting up a conference.

• Media source error: correspond to gUM failures, i.e., error during configuring user’s media device (mic, camera, screen-capture).
• SDP generation error: are related to the error callbacks returned from createOffer() or createAnswer(), i.e., errors during configuring the local media pipeline.
• Negotiation failure: are related to error callbacks returned from setLD() and setRD(), i.e., negotiation errors may occur due to differing media and network configuration between endpoints.
• ICE connection failure: when ICE failed to establish connectivity, these failures may occur when NAT/firewall traversal fails.
• Transport failure: these failures occurs after the call is successfully establishment, i.e., media stops flowing between participants. This may occur due to loss in connectivity, system load, triggered circuit breaker, or revoking consent.

Figure 1: Failures at different stages of setting up a WebRTC session.

Today, we are announcing a new API: reportError to find out the other causes of failure, when do they occur, why they occur, and what ratio of the failure corresponds to the quirks of different implementations (eg. browser or conference bridge) versus NAT traversal failure.

The WebRTC APIs either have a callback or a promise associated to them. WebRTC applications can now use reportError() to capture at which stage the negotiation fails and pass on the DomError returned by the callback or promise to callstats.io. See Section enumerating WebRTC functions for details.

The example below reports error when creating an SDP offer:

  //adding Fabrics
  var pc_config = {"iceServers": [{url: "stun:stun.example.org:3478"}]};
  var pc = new RTCPeerConnection(pc_config);

  function pcCallback (err, msg) {
    console.log("Monitoring status: "+ err + " msg: " + msg);
  };

  function createOfferError(err) {
    callStats.reportError(pc,confID,callStats.webRTCFunctions.createOffer,err);
  }
  //remoteUserId is the recipient's userID
  //conferenceID is generated or provided by the origin server (webrtc service)

  // let the "negotiationneeded" event trigger offer generation
  pc.onnegotiationneeded = function () {

    // pc is created, tell callstats about it
    // pick a fabricUsage enumeration, if pc is sending both media and data: use multiplex.
    var usage = callStats.fabricUsage.multiplex;
    callStats.addNewFabric(pc, remoteUserID, usage, confID, pcCallback);

    // create offer
    pc.createOffer(localDescCreated, createOfferError);
  }

The example below reports error when creating an SDP answer:

  function createAnswerError(err){
    callStats.reportError(pc,confID,callStats.webrtcfunctions.createAnswer,err);
  }

  function doAnswer() {
     pc.createAnswer(setLocalAndSendMessage, createAnswerError, sdpConstraints);
  }

The failure reason will appear both in the conference timeline for individual participants and aggregate values on the main dashboard (screenshot on the way!) will appear under each subcategory.

This new feature is extremely useful for many developers, as it highlights where failures occur in a WebRTC application and helps to build better products. It is keeping with our vision to help our customers deliver high quality communication applications. If you are interested in monitoring WebRTC calls, send us an email to support-at-callstats.io to get your coupon for a 30-day free trial.