RTCMetricsCollector

RTCMetricsCollector is a component for collecting, batching, compressing, and sending WebRTC statistics from an RTCPeerConnection to a backend service according to a server-defined contract.

The class encapsulates all low-level logic required to:

• read WebRTC statistics via getStats()
• extract and track metric headers
• batch and deduplicate metric values
• compress metric payloads
• send data over WebSocket or HTTP
• handle errors and stop collection when limits are exceeded

This class is intended to be used as part of a WebRTC SDK or metrics pipeline.

Purpose

RTCMetricsCollector is designed to solve the following problems:

• Periodic collection of WebRTC statistics
• Strict adherence to a backend-defined metrics schema
• Efficient network usage through batching, deduplication, and compression
• Automatic handling of changes in RTCStats structure during a session
• Decoupling metrics collection from transport implementation

The collector does not know how metrics are transported. Transport is delegated to an implementation of IRTCMetricsSender.

High-Level Architecture

RTCPeerConnection
↓ getStats()
RTCMetricsCollector
↓
RTCMetricsBatch → Compressor
↓
IRTCMetricsSender (WebSocket or HTTP)

Key Features

• Collection of metrics by RTCStats type (codec, transport, outbound-rtp, etc.)
• Automatic extraction and tracking of metric headers
• Re-sending headers when stats structure changes
• Fixed-size batching of metrics
• Deduplication of repeated values between batch rows
• Optional compression (none or gzip)
• Custom report filters
• Automatic shutdown after exceeding error threshold

Basic Usage

const collector = new RTCMetricsCollector(
    "media-session-id",
    serverDescription,
    peerConnection,
    sender,
    logger,
    3
);

await collector.start();

Constructor

new RTCMetricsCollector(
    id
:
string,
    description
:
RTCMetricsServerDescription,
    peerConnection
:
RTCPeerConnection,
    sender
:
IRTCMetricsSender,
    logger
:
ILogger,
    maxErrors
:
number
)

Parameters

| Parameter | Description | |----------------|------------------------------------| | id | Unique media session identifier | | description | Server-defined metrics description | | peerConnection | WebRTC peer connection | | sender | Metrics transport implementation | | logger | Logger instance | | maxErrors | Maximum allowed send errors |

Lifecycle

start()

await collector.start();

• Validates configuration
• Extracts and sends initial metric headers
• Starts periodic collection if enabled in description

stop()

collector.stop();

• Stops periodic sampling
• Resets internal state

Enable / Disable Collection

collector.collect(true);
collector.collect(false);

Filters

Custom filters can be added to exclude specific RTCStats reports:

collector.addStatsReportFilter({
    allowed(report) {
        return report.kind !== "video";
    }
});

If any filter returns false, the report is ignored.

Headers Handling

The collector dynamically builds a list of metric headers from RTCStats reports.

If the header structure changes:

• the current batch is flushed
• updated headers are sent to the backend

This guarantees that the backend can always correctly interpret incoming metric batches.

Batching and Deduplication

• Metrics are accumulated into a RTCMetricsBatch
• When batchSize is reached, the batch is sent
• Duplicate values compared to the previous row are replaced with empty strings
• This significantly reduces payload size

Compression

Compression type is defined by the server description:

• none
• gzip

Compression is applied automatically before sending a batch.

Error Handling

• Failed send attempts increment an internal error counter
• When the counter exceeds maxErrors, collection is stopped automatically

When to Use

Use RTCMetricsCollector when you need:

• Continuous WebRTC statistics collection
• Efficient, low-overhead metrics transport
• Dynamic handling of stats structure changes
• A clean separation between metrics logic and transport

When Not to Use

RTCMetricsCollector may be unnecessary if:

• You only need a one-time getStats() call
• Metrics are not sent to a backend
• Batching and compression are not required

In such cases, direct usage of RTCPeerConnection.getStats() may be sufficient.

Related Components

• RTCMetricsCollectorBuilder — helper for constructing collectors
• RTCMetricsBatch — batch storage and deduplication
• IRTCMetricsSender — metrics transport interface
• RTCMetricsServerDescription — server-side metrics contract