How to trace custom events into your rtcstats dump

Send your own application events, like a user rating or a UI action, into the same rtcstats dump file so they sit alongside the WebRTC traces.

The rtcstats dump captures everything the browser tells you about a WebRTC session. Sometimes you want more than that: the moment a user rated the call, the point where they switched cameras, or a state change in your own application. Custom events let you push those into the same dump file, so your app-level context and the WebRTC traces live together in one timeline.

This is a client-side feature of rtcstats-js. You do not need to change rtcstats-server to send them.

Prerequisite: rtcstats-js integrated

Custom events go through the same tracing object you already use to collect WebRTC data. If you have not wired rtcstats-js into your client yet, start with the integration guide.

The tracing object is created once when your app loads:

import { wrapRTCStatsWithDefaultOptions } from '@rtcstats/rtcstats-js';

const trace = wrapRTCStatsWithDefaultOptions();
trace.connect('wss://your-domain.example.com/' + window.location.pathname);

trace is the function you call to record a custom event.

The trace signature

trace(methodName, peerConnection, data);

Argument	What to pass
`methodName`	The event name. It must start with a colon (`:`), for example `:userRating`. The colon namespaces your events so they never collide with the built-in WebRTC methods rtcstats-js traces.
`peerConnection`	The `RTCPeerConnection` this event relates to, or `null` if it is not tied to a specific connection.
`data`	A JavaScript string or object with your payload. It is JSON-encoded when sent to the server. Pass `null` if there is no extra data.

You do not add a timestamp. The trace function stamps the event for you when it is called.

Example: record a user rating

Say you show a star rating after a call ends and you want it in the dump next to the connection it refers to:

function onCallRated(peerConnection, stars, comment) {
  trace(':userRating', peerConnection, {
    stars: stars,
    comment: comment,
  });
}

Now a one-star rating sits in the same dump as the packet loss and ICE failures that likely caused it. No more guessing which session a complaint maps to.

Example: an event not tied to a connection

Some events are about the session as a whole, not one peer connection. Pass null:

trace(':networkChange', null, { from: 'wifi', to: 'cellular' });

// No payload needed, just the fact that it happened:
trace(':userClickedReconnect', null, null);

Where they show up in rtcstats.com

Custom events appear in the Logs page of the session, in the same timeline as the WebRTC events. They are marked with an APP badge and shown without the leading colon, and the Custom filter button isolates them. Events traced with peerConnection = null have no peer connection: the PC column shows a dash and they are grouped under an Unassigned entry in the Peers selector.

Good events to trace

User feedback - ratings, thumbs up/down, "this call was bad" reports
App state changes - camera or microphone switches, screen-share start/stop, reconnect attempts
Network context - the user moved from wifi to cellular, or your app detected a degraded network
Business context - the queue or route a contact-center call came in on, the feature flag that was active

Keep the payloads small and free of PII. If an identifier is sensitive, hash it before you trace it.

Notes and limits

rtcstats-server does not process custom events by default. They are stored in the dump as-is. If you want to act on them, for example to enrich your database, you add that handling yourself. See associating your call and meeting IDs for the pattern of pulling extra fields out of the collected data.
Do not use compression for custom methods. Custom events must be sent uncompressed.
Always prefix with a colon. An event name without the leading : risks clashing with a real WebRTC method name and will not behave the way you expect.