How to use session, conference and user identifiers

Understanding and configuring session, conference, and user identifiers in rtcStats for correlating and finding sessions.

One of the most important aspects of setting up rtcStats in production is properly configuring identifiers. These allow you to find specific sessions, correlate multiple participants in the same call, and tie sessions back to users in your own system.

The three identifiers

rtcStats enables you to use and populate three key identifiers:

Identifier	What it represents	Example
session	A single browser session collecting WebRTC metrics. One participant, one browser tab	`sess_abc123`
conference	A call or meeting room that multiple participants join. Groups sessions together	`room_meeting-42`
user	The user in your system. Can have multiple sessions over time	`user_def456`

How they relate

A typical video call scenario:

Alice and Bob join a meeting room called "standup"
This creates 1 conference (standup), 2 sessions (one per participant), and 2 users
If Alice disconnects and rejoins, she gets a new session but keeps the same user and conference identifier.

Setting identifiers in rtcstats.js

These identifiers are part of the rtcstats connect token which is generated by your API. See the example server for an implementation:

import { generateAuthToken } from '@rtcstats/rtcstats-server/utils.js';

generateAuthToken({
    user: 'user_def456',
    session: 'sess_abc123',
    conference: 'room_meeting-42',
}, config.authorization.jwtSecret).then(token => /* send token to client */)

The parameters are optional but at least a unique session id should be set to allow querying the database for a particular connection.

Session identifiers should be unique, i.e. a UUID. Conference and user names can match the ones existing elsewhere in your system but are opaque strings for rtcstats.

The token is a signed JSON Web Token (JWT) which allows rtcstats-server to authenticate the connection and trust the values. rtcstats-server and the API generating the token MUST be configured with the same shared secret. See here for details.

The token is then passed as a query parameter to the rtcstats-js connect method:

trace.connect('wss://your-domain.example.com/?rtcstats-token=' + token);

If the token is not considered valid by rtcstats-server the connection will be rejected.

rtcstats-server then extracts the fields user, session and conference into the rtcstats_user, rtcstats_session and rtcstats_conference database fields that are part of the rtcstats-server table.

Finding sessions using identifiers

Once configured, you can find sessions via the SQL database:

In the SQL database

Here are some sample queries using the identifiers:

Find all sessions for a specific user

SELECT 
    session_start, 
    session_end, 
    rtcstats_session, 
    rtcstats_conference
FROM "rtcstats-server"
WHERE rtcstats_user = 'user_def456'
ORDER BY session_start DESC;

Find all participants in a specific conference

SELECT 
    session_start, 
    session_end, 
    rtcstats_session, 
    rtcstats_user
FROM "rtcstats-server"
WHERE rtcstats_conference = 'room_meeting-42'
ORDER BY session_start DESC;

Find all sessions from a specific user in the last 7 days

SELECT 
    session_start, 
    session_end, 
    rtcstats_session, 
    rtcstats_conference
FROM "rtcstats-server"
WHERE rtcstats_user = 'user_def456'
    AND session_start >= CURRENT_DATE AT TIME ZONE 'UTC' - INTERVAL '7 days'
ORDER BY session_start DESC;

Best practices

Use random identifiers - don't use meaningful identifiers that may expose user names, emails, companies or even room names - all these will break privacy. Use hashed values or random UUIDs instead.
Always set conference - without it, you can't correlate participants in the same call, which is essential for troubleshooting ("Alice hears Bob fine, but Bob can't hear Alice").
Be consistent - use the same identifiers in your own logs, support tickets, and analytics so you can cross-reference easily.