npm package: @flashphoner/web-sdk-metrics
Description: Official Flashphoner RTC metrics collector
Author: Flashphoner
Latest version: 1.0.11

# 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

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

await collector.start();
```

---

## Constructor

```ts
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()

```ts
await collector.start();
```

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

---

### stop()

```ts
collector.stop();
```

- Stops periodic sampling
- Resets internal state

---

### Enable / Disable Collection

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

---

## Filters

Custom filters can be added to exclude specific RTCStats reports:

```ts
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