@observertc/client-monitor-js 3.4.1-e6caa47.0 → 3.5.0

package/README.md

@@ -7,11 +7,22 @@ Table of Contents:
 -   [Quick Start](#quick-start)
 -   [Integrations](#integrations)
     -   [Mediasoup](#mediasoup)
+-   [Collected Metrics](#collected-metrics)
+    -   [Calculated updates](#calculated-updates)
+    -   [PeerConnection Entry](#peerconnection-entry)
+    -   [MediaStreamTrack Entry](#mediastreamtrack-entry)
+    -   [InboundRTP Entry](#inboundrtp-entry)
+    -   [OutboundRTP Entry](#outboundrtp-entry)
 -   [Detectors and Alerts](#detectors-and-alerts)
     -   [Audio Desync Detector](#audio-desync-detector)
     -   [CPU Performance Detector](#cpu-performance-detector)
--   [Calculated updates](#calculated-updates)
 -   [Configurations](#configurations)
+-   [Events](#events)
+    -   [CLIENT_JOINED Event](#client_joined-event)
+    -   [CLIENT_LEFT Event](#client_left-event)
+    -   [Custom Call Event](#custom-call-event)
+    -   [Extension Stats Event](#extension-stats-event)
+-   [Sampling](#sampling)
 -   [NPM package](#npm-package)
 -   [API docs](#api-docs)
 -   [Schemas](#schemas)
@@ -25,6 +36,10 @@ Install it from [npm](https://www.npmjs.com/package/@observertc/client-monitor-j
 ```
 npm i @observertc/client-monitor-js
 ```
+or
+```
+yarn add @observertc/client-monitor-js
+```
 
 Add `@observertc/client-monitor-js` to your WebRTC app.
 
@@ -35,18 +50,17 @@ const config = {
     collectingPeriodInMs: 5000,
 };
 const monitor = createClientMonitor(config);
-const statsCollector = monitor.collectors.collectFromRTCPeerConnection(peerConnection);
+const collector = monitor.collectors.addRTCPeerConnection(peerConnection);
 
 monitor.on("stats-collected", () => {
-    const storage = monitor.storage;
-    for (const inboundRtp of storage.inboundRtps()) {
+    for (const inboundRtp of monitor.inboundRtps) {
         const trackId = inboundRtp.getTrackId();
         const remoteOutboundRtp = inboundRtp.getRemoteOutboundRtp();
         console.log(trackId, inboundRtp.stats, remoteOutboundRtp.stats);
     }
 });
 // if you want to stop collecting from the peerConnection, then:
-statsCollector.close();
+collector.close();
 ```
 
 The above example do as follows:
@@ -69,123 +83,314 @@ const config = {
     collectingPeriodInMs: 5000,
 };
 const monitor = createClientMonitor(config);
-const mediasoupStatsCollector = monitor.collectors.collectFromMediasoupDevice(mediasoupDevice);
+const collector = monitor.collectors.addMediasoupDevice(mediasoupDevice);
+
+collector.onclose = () => {
+    console.log(`mediasoup collector ${collector.id} is closed`);
+}
 
 monitor.on("stats-collected", () => {
     // do your stuff
 
     // you can close detach mediasoup
     // collector by calling the close
-    mediasoupStatsCollector.close();
+    collector.close();
 });
 ```
 
-**Important Note**: The created collector is hooked on the device 'newtransport' event,
-and can detect transports automatically when they are created after the device is added.
-If you create transports before you add the device to the monitor,  
-transports you created before will not be monitored automatically, you need to add them
-to the statscollector, like this:
+**Important Note**: The created collector is hooked to the device's 'newtransport' event and can automatically detect transports created **after** the device has been added. If you create transports before adding the device to the monitor, those previously created transports will not be monitored automatically. You will need to manually add them to the stats collector like this:
 
 ```javascript
-const myTransport = mediasoupStatsCollector.addTransport(myTransport); // your transport created before the device is added to the monitor
+const myTransport = collector.addTransport(myTransport); // your transport created before the device is added to the monitor
 ```
 
-## Calculated Updates
+## Collected Metrics
 
-The Calculated Updates lets you observer metrics derived from the polled webrtc stats captured by the library. These calculated updates provide a richer, more nuanced understanding of your application's client-side behavior, offering valuable insights beyond what raw stats metrics can give you.
+Collecting WebRTC Metrics is either done periodically according to the `collectingPeriodInMs` configuration or manually by calling the `monitor.collect()` method. The collected metrics are stored in the `ClientMonitor` instance and assigned to Entries.
+Each entry in clientMonitor represents a WebRTC component such as `RTCPeerConnection`, `MediaStreamTrack`, etc. Entries can relate to each other and from one entry you can navigate to a correspondent entry. For example, from an `InboundRTP` entry you can navigate to the correspondent `RemoteOutboundRtp` entry, and reverse. Additionally entries are exposing basic derivatives calculated from the collected metrics.
 
-### Storage Updates
 
-```javascript
-import { createClientMonitor } from 'client-monitor-js';
+### Calculated Updates
 
-// Create a ClientMonitor instance
-const monitor = createClientMonitor({
-    collectingPeriodInMs: 2000,
-});
+Calculated updates allow you to observe metrics derived from polled WebRTC stats captured by the library. These calculated updates provide a richer, more nuanced understanding of your application's client-side behavior, offering valuable insights beyond what raw stats metrics can provide.
+
+For example by accessing `storage` you can get the following calculated updates:
+
+```javascript
 
-const storage = monitor.storage;
 monitor.on('stats-collected', () => {
-    console.log('average RTT in seconds', storage.avgRttInS);
-    console.log('Sending audio bitrate', storage.sendingAudioBitrate);
-    console.log('Sending video bitrate', storage.sendingVideoBitrate);
-    console.log('Receiving audio bitrate', storage.receivingAudioBitrate);
-    console.log('Receiving video bitrate', storage.receivingVideoBitrate);
+    const {
+        totalInboundPacketsLost,
+        totalInboundPacketsReceived,
+        totalOutboundPacketsLost,
+        totalOutboundPacketsReceived,
+        totalOutboundPacketsSent,
+        totalSentAudioBytes,
+        totalSentVideoBytes,
+        totalReceivedAudioBytes,
+        totalReceivedVideoBytes,
+        totalDataChannelBytesSent,
+        totalDataChannelBytesReceived,
+    
+        deltaInboundPacketsLost,
+        deltaInboundPacketsReceived,
+        deltaOutboundPacketsLost,
+        deltaOutboundPacketsReceived,
+        deltaOutboundPacketsSent,
+        deltaSentAudioBytes,
+        deltaSentVideoBytes,
+        deltaReceivedAudioBytes,
+        deltaReceivedVideoBytes,
+        deltaDataChannelBytesSent,
+        deltaDataChannelBytesReceived,
+    
+        avgRttInS,
+        sendingAudioBitrate,
+        sendingVideoBitrate,
+        receivingAudioBitrate,
+        receivingVideoBitrate,
+    } = monitor.storage
+
+    console.log(`Total inbound packets lost: ${totalInboundPacketsLost}`);
+    console.log(`Total inbound packets received: ${totalInboundPacketsReceived}`);
+    console.log(`Total outbound packets lost: ${totalOutboundPacketsLost}`);
+    console.log(`Total outbound packets received: ${totalOutboundPacketsReceived}`);
+    console.log(`Total outbound packets sent: ${totalOutboundPacketsSent}`);
+    console.log(`Total sent audio bytes: ${totalSentAudioBytes}`);
+    console.log(`Total sent video bytes: ${totalSentVideoBytes}`);
+    console.log(`Total received audio bytes: ${totalReceivedAudioBytes}`);
+    console.log(`Total received video bytes: ${totalReceivedVideoBytes}`);
+    console.log(`Total data channel bytes sent: ${totalDataChannelBytesSent}`);
+    console.log(`Total data channel bytes received: ${totalDataChannelBytesReceived}`);
+
+    console.log(`Lost Inbound packets since last collecting: ${deltaInboundPacketsLost}`);
+    console.log(`Received Inbound packets since last collecting: ${deltaInboundPacketsReceived}`);
+    console.log(`Lost Outbound packets since last collecting: ${deltaOutboundPacketsLost}`);
+    console.log(`Received Outbound packets since last collecting: ${deltaOutboundPacketsReceived}`);
+    console.log(`Sent Outbound packets since last collecting: ${deltaOutboundPacketsSent}`);
+    console.log(`Sent audio bytes since last collecting: ${deltaSentAudioBytes}`);
+    console.log(`Sent video bytes since last collecting: ${deltaSentVideoBytes}`);
+    console.log(`Received audio bytes since last collecting: ${deltaReceivedAudioBytes}`);
+    console.log(`Received video bytes since last collecting: ${deltaReceivedVideoBytes}`);
+    console.log(`Data channel bytes sent since last collecting: ${deltaDataChannelBytesSent}`);
+    console.log(`Data channel bytes received since last collecting: ${deltaDataChannelBytesReceived}`);
+
+    console.log(`Average RTT: ${avgRttInS}`);
+    console.log(`Sending audio bitrate: ${sendingAudioBitrate}`);
+    console.log(`Sending video bitrate: ${sendingVideoBitrate}`);
+    console.log(`Receiving audio bitrate: ${receivingAudioBitrate}`);
+    console.log(`Receiving video bitrate: ${receivingVideoBitrate}`);
+    
+});
 
 ```
 
-### PeerConnection Updates
+As mentioned above, the `ClientMonitor` instance stores entries, and each entry has a `stats` property that contains the raw stats collected from the WebRTC API. The `ClientMonitor` also stores calculated updates for each entry, which are derived from the raw stats. These calculated updates are accessible from the `ClientMonitor` instance and are updated every time the `stats-collected` event is emitted.
+
+### PeerConnection Entry
 
+**Accessing Stats**:
 ```javascript
-import { createClientMonitor } from "client-monitor-js";
+// from monitor
+monitor.peerConnections.forEach(pc => console.log(`PeerConnection: ${pc.statsId}`, pc.stats));
 
-// Create a ClientMonitor instance
-const monitor = createClientMonitor({
-    collectingPeriodInMs: 2000,
-});
+// or from storage
+[...monitor.storage.peerConnections()].forEach(pc => console.log(`PeerConnection: ${pc.statsId}`, pc.stats));
+```
 
-const storage = monitor.storage;
-monitor.on("stats-collected", () => {
-    for (const peerConnection of storage.peerConnections()) {
-        console.log("average RTT in seconds", peerConnection.avgRttInS);
-        console.log("Sending audio bitrate on PC", peerConnection.sendingAudioBitrate);
-        console.log("Sending video bitrate on PC", peerConnection.sendingVideoBitrate);
-        console.log("Receiving audio bitrate on PC", peerConnection.receivingAudioBitrate);
-        console.log("Receiving video bitrate on PC", peerConnection.receivingVideoBitrate);
+**Accessing Calculated Updates**:
+```javascript
+
+monitor.on('stats-collected', () => {
+    for (const pc of monitor.peerConnections) {
+        console.log(`Between this and last collecting, the following stats were calculated for PeerConnection`, [
+            `Received bytes through data channel ${pc.deltaDataChannelBytesReceived}`,
+            `Sent bytes through data channel ${pc.deltaDataChannelBytesSent}`,
+            `Received bytes through inbound rtps ${pc.deltaInboundPacketsReceived}`,
+            `Sent bytes through outbound rtps ${pc.deltaOutboundPacketsSent}`,
+            `Lost packets on inbound rtps ${pc.deltaInboundPacketsReceived}`,
+            `Lost packets on outbound rtps ${pc.deltaOutboundPacketsSent}`,
+            `Outbound audio bitrate${pc.sendingAudioBitrate}`,
+            `Outbound video bitrate${pc.sendingVideoBitrate}`,
+            `Inbound audio bitrate${pc.receivingAudioBitrate}`,
+            `Inbound video bitrate${pc.receivingVideoBitrate}`,
+            `Received bytes on all audio tracks ${pc.deltaReceivedAudioBytes}`,
+            `Received bytes on all video tracks ${pc.deltaReceivedVideoBytes}`,
+            `Sent bytes on all audio tracks ${pc.deltaSentAudioBytes}`,
+            `Sent bytes on all video tracks ${pc.deltaSentVideoBytes}`,
+        ].join('\n'));
     }
 });
 ```
 
-### Inbound RTP stats updates
+**Accessing related entries**:
 
 ```javascript
-import { createClientMonitor } from "client-monitor-js";
+    const pc = monitor.getPeerConnectionStats(peerConnectionId);
+    if (pc) {
+        [...pc.inboundRtps()].forEach((inboundRtp) => void 0);
+        [...pc.outboundRtps()].forEach((outboundRtp) => void 0);
+
+        [...pc.localCandidates()].forEach((localICECandidate) => void 0);
+        [...pc.remoteCandidates()].forEach((remoteICECandidate) => void 0);
+        [...pc.iceCandidatePairs()].forEach((iceCandidatePair) => void 0);
+
+        [...pc.sctpTransports()].forEach((sctpTransport) => void 0);
+        [...pc.transceivers()].forEach((transceiver) => void 0);
+        [...pc.senders()].forEach((sender) => void 0);
+        [...pc.receivers()].forEach((receiver) => void 0);
+        [...pc.transports()].forEach((transport) => void 0);
+        [...pc.certificates()].forEach((certificate) => void 0);
+        [...pc.iceServers()].forEach((iceServer) => void 0);
+        
+    }
+```
 
-// Create a ClientMonitor instance
-const monitor = createClientMonitor({
-    collectingPeriodInMs: 2000,
-});
+### MediaStreamTrack Entry
 
-const storage = monitor.storage;
-monitor.on("stats-collected", () => {
-    for (const inboundRtp of storage.inboundRtps()) {
-        console.log("mean opinion score for inbound-rtp", inboundRtp.score);
 
-        console.log("receiving bitrate", inboundRtp.receivingBitrate);
-        console.log("lost packets since last stats-collected", inboundRtp.lostPackets);
-        console.log("received packets since last stats-collected", inboundRtp.receivedPackets);
-        console.log("decoded frames since last stats-collected", inboundRtp.decodedFrames);
+**Collected tracks**:
+```javascript
+monitor.on('stats-collected', () => {
+    for (const track of monitor.tracks) {
+        console.log(`Track ${track.trackId} is ${track.kind}`);
     }
 });
 ```
 
-### Outbound RTP stats updates
+**Accessing Calculated Updates**:
+```javascript
+monitor.on('stats-collected', () => {
+    for (const track of monitor.tracks) {
+        if (track?.direction === 'outbound') {
+            console.log(`Stats belongs to Track ${track.trackId} `);
+            console.log(`Lost packets reported by remote endpoint: ${track.remoteLostPackets}`);
+            console.log(`Received packets reported by remote endpoint: ${track.remoteReceivedPackets}`);
+            console.log(`Sent packets reported by local endpoint: ${track.sentPackets}`);
+            console.log(`Sending bitrate ${track.sendingBitrate}`);
+            console.log(`Associated sfu stream id: ${track.sfuStreamId}`);
+        }
+
+        if (trackStats?.direction === 'inbound') {
+            console.log(`Stats belongs to Track ${track.trackId} `);
+            console.log(`Lost packets reported by local endpoint: ${track.lostPackets}`);
+            console.log(`Received packets reported by local endpoint: ${track.receivedPackets}`);
+            console.log(`Received bitrate ${track.receivingBitrate}`);
+            console.log(`Associated sfu stream id: ${track.sfuStreamId}`);
+            console.log(`Associated sfu sink id: ${track.sfuSinkId}`);
+        }
+    }
+});
+```
 
+**Accessing related entries**
 ```javascript
-import { createClientMonitor } from "client-monitor-js";
+monitor.on('stats-collected', () => {
+    for (const track of monitor.tracks) {
+        console.log(`Track ${track.trackId} is ${track.kind}`);
+        if (track.direction === 'outbound') {
+            [...track.outboundRtps()].forEach(outboundRtp => {
+                console.log(`Outbound RTP ${outboundRtp.getSsrc()} has ${outboundRtp.sentPackets} sent packets`);
+            });
+        }
+
+        if (track.direction === 'inbound') {
+            [...track.inboundRtps()].forEach(inboundRtp => {
+                console.log(`Inbound RTP ${inboundRtp.getSsrc()} has ${inboundRtp.receivedPackets} received packets`);
+            });
+        }
+    }
+});
+```
 
-// Create a ClientMonitor instance
-const monitor = createClientMonitor({
-    collectingPeriodInMs: 2000,
+### InboundRTP Entry
+
+**Accessing Stats**:
+
+```javascript
+monitor.on('stats-collected', () => {
+    for (const inboundRtp of monitor.inboundRtps) {
+        console.log(`InboundRtp ${inboundRtp.statsId} collected stats`, inboundRtp.stats);
+    }
+});
+```
+**Accessing Calculated Updates**:
+```javascript
+monitor.on('stats-collected', () => {
+    for (const inboundRtp of monitor.inboundRtps) {
+        console.log(`InboundRtp ${inboundRtp.getSsrc()} `);
+        console.log(`Received packets since last collecting: ${inboundRtp.receivedBytes}`);
+        console.log(`Received bitrate since last collecting: ${inboundRtp.receivingBitrate}`);
+        console.log(`Received packets since last collecting: ${inboundRtp.receivedPackets}`);
+        console.log(`Received frames since last collecting: ${inboundRtp.receivedFrames}`);
+        console.log(`Lost packets since last collecting: ${inboundRtp.lostPackets}`);
+        console.log(`Average jitter buffer delay since last collecting: ${inboundRtp.avgJitterBufferDelayInMs}`);
+        console.log(`Average RTT since last collecting: ${inboundRtp.avgRttInS}s`);
+
+        console.log(`Associated sfu stream id: ${inboundRtp.sfuStreamId}`);
+        console.log(`Associated sfu sink id: ${inboundRtp.sfuSinkId}`);
+        
+    }
 });
+```
 
-const storage = monitor.storage;
-monitor.on("stats-collected", () => {
-    for (const outboundRtp of storage.outboundRtps()) {
-        console.log("stability score outbound-rtp", outboundRtp.score);
+**Accessing related entries**:
+```javascript
+monitor.on('stats-collected', () => {
+    for (const inboundRtp of monitor.inboundRtps) {
+        
+        console.log(`inbound RTP associated with SSRC ${inboundRtp.getSsrc()} uses codec ${inboundRtp.getCodec()?.stats.mimeType}`);
+        console.log(`inbound RTP associated with SSRC ${inboundRtp.getSsrc()} remote endpoint sent ${inboundRtp.getRemoteOutboundRtp()?.stats.packetsSent} packets`);
 
-        console.log("sending bitrate", outboundRtp.sendingBitrate);
-        console.log("sent packets since last stats-collected", outboundRtp.sentPackets);
+        inboundRtp.kind ==='audio' && console.log(`inbound RTP associated with SSRC ${inboundRtp.getSsrc()} has played out ${inboundRtp.getAudioPlayout()?.stats.totalSamplesCount} audio samples`);
 
-        const remoteInboundRtp = outboundRtp.getRemoteInboundRtp();
-        console.log(
-            "Received packets on remote inbound-rtp belongs to this outbound-rtp",
-            remoteInboundRtp?.receivedPackets
-        );
+        const audioPlayout = inboundRtp.getAudioPlayout(); // The AudioPlayoutEntry associated with the inboundRtp
+        const peerConnection = inboundRtp.getPeerConnection(); // The PeerConnectionEntry associated with the inboundRtp
+        const trackId = inboundRtp.getTrackId(); // The trackId associated with the inboundRtp
+    }
+})
+```
+
+### OutboundRTP Entry
+
+**Accessing Stats**:
+
+```javascript
+monitor.on('stats-collected', () => {
+    for (const outboundRtp of monitor.outboundRtps) {
+        console.log(`OutboundRtp ${outboundRtp.statsId} collected stats`, outboundRtp.stats);
     }
 });
 ```
 
+**Accessing Calculated Updates**:
+```javascript
+monitor.on('stats-collected', () => {
+    for (const outboundRtp of monitor.outboundRtps) {
+        console.log(`OutboundRtp ${outboundRtp.getSsrc()} `);
+        console.log(`Sent packets since last collecting: ${outboundRtp.sentPackets}`);
+        console.log(`Sending bitrate since last collecting: ${outboundRtp.sendingBitrate}`);
+        console.log(`Sent bytes since last collecting: ${outboundRtp.sentBytes}`);
+        console.log(`Associated sfu stream id: ${outboundRtp.sfuStreamId}`);
+    }
+});
+```
+
+**Accessing related entries**:
+```javascript
+monitor.on('stats-collected', () => {
+    for (const outboundRtp of monitor.outboundRtps) {
+        console.log(`outbound RTP associated with SSRC ${outboundRtp.getSsrc()} uses codec ${outboundRtp.getCodec()?.stats.mimeType}`);
+        console.log(`outbound RTP associated with SSRC ${outboundRtp.getSsrc()} remote endpoint received ${outboundRtp.getRemoteInboundRtp()?.stats.packetsReceived} packets`);
+
+        const remoteInboundRtp = outboundRtp.getRemoteInboundRtp(); // The RemoteInboundRtpEntry associated with the outboundRtp
+        const peerConnection = outboundRtp.getPeerConnection(); // The PeerConnectionEntry associated with the outboundRtp
+        const trackId = outboundRtp.getTrackId(); // The trackId associated with the outboundRtp
+    }
+})
+```
+
+
 ## Detectors and Alerts
 
 Detectors and alerts provide events of tracking and responding to anomalies or performance issues based on the polled stats. Detectors are components that continuously monitor for specific conditions in the polled stats, and set an alert if certain thresholds are hit. You can subscribe to alerts of an instantiated client-monitor-js and configure detectors via initial configurations.
@@ -281,6 +486,7 @@ const config = {
      * By setting this, the observer makes samples after n number or collected stats.
      *
      * For example if the value is 10, the observer makes a sample after 10 collected stats (in every 10 collectingPeriodInMs).
+     * if the value is less or equal than 0
      *
      * DEFAULT: 1
      */
@@ -288,6 +494,122 @@ const config = {
 };
 ```
 
+## Events
+
+In the context of our monitoring library, events play a crucial role in enabling real-time insights and interactions. These events are emitted by the monitor to signal various occurrences, such as the creation of a peer connection, media track, or ICE connections. Below, we detail the events detected by the monitor.
+ * `CLIENT_JOINED`: A client has joined
+ * `CLIENT_LEFT`: A client has left
+ * `PEER_CONNECTION_OPENED`: A peer connection is opened
+ * `PEER_CONNECTION_CLOSED`: A peer connection is closed
+ * `MEDIA_TRACK_ADDED`: A media track is added
+ * `MEDIA_TRACK_REMOVED`: A media track is removed
+ * `MEDIA_TRACK_MUTED`: A media track is muted
+ * `MEDIA_TRACK_UNMUTED`: A media track is unmuted
+ * `ICE_GATHERING_STATE_CHANGED`: The ICE gathering state has changed
+ * `PEER_CONNECTION_STATE_CHANGED`: The peer connection state has changed
+ * `ICE_CONNECTION_STATE_CHANGED`: The ICE connection state has changed
+ * `DATA_CHANNEL_OPEN`: A data channel is opened
+ * `DATA_CHANNEL_CLOSED`: A data channel is closed
+ * `DATA_CHANNEL_ERROR`: A data channel error occurred
+
+For Mediasoup integration the following events are detected:
+ * `PRODUCER_ADDED`: A producer is added
+ * `PRODUCER_REMOVED`: A producer is removed
+ * `PRODUCER_PAUSED`: A producer is paused
+ * `PRODUCER_RESUMED`: A producer is resumed
+ * `CONSUMER_ADDED`: A consumer is added
+ * `CONSUMER_REMOVED`: A consumer is removed
+ * `CONSUMER_PAUSED`: A consumer is paused
+ * `CONSUMER_RESUMED`: A consumer is resumed
+ * `DATA_PRODUCER_ADDED`: A data producer is added
+ * `DATA_PRODUCER_REMOVED`: A data producer is removed
+ * `DATA_CONSUMER_ADDED`: A data consumer is added
+ * `DATA_CONSUMER_REMOVED`: A data consumer is removed
+
+### CLIENT_JOINED Event
+
+A client event is automatically generated when the first sample is created, and 
+the joined timestamp is set to the time of the monitor creation. However, you can
+manually set the event by calling the `monitor.join()` method. 
+
+**Important Note**: The `monitor.join()` method is called only once, and in case of manual setup it should be called before the first sample is created.
+
+```javascript
+monitor.join({
+    timestamp: Date.now(),
+});
+```
+
+### CLIENT_LEFT Event
+
+A client event is automatically generated when the monitor is closed, and the left timestamp is set to the time of the monitor closing. However, you can manually set the event by calling the `monitor.leave()` method.
+
+**Important Note**: The `monitor.leave()` method is called only once, and in case of manual setup it should be called before the monitor is closed.
+
+```javascript
+monitor.leave({
+    timestamp: Date.now(),
+});
+```
+
+
+### Custom Call Event
+
+You can create a custom event by calling the `monitor.addCustomCallEvent()` method. The method takes an object with the following properties:
+
+```javascript
+monitor.addCustomCallEvent({
+    name: 'MY CUSTOM EVENT', // mandatory
+
+    message: 'my custom message', // optional;
+    attachments: JSON.stringify({
+        value: 'my custom value',
+    }), // optional
+	timestamp: Date.now(), // optional
+	value: `simple string value`, // optional
+	peerConnectionId: 'peer-connection-id', // optional;
+	mediaTrackId: 'media-track-id', // optional;
+	
+});
+```
+
+### Extension Stats Event
+
+You can create an extension state event by calling the `monitor.addExtensionStats()` method. The method takes an object with the following properties:
+
+```javascript
+monitor.addExtensionStats({
+    type: 'CLIENT_CPU_STATS',
+    payload: {
+        cpuUsage: 0.5,
+        memoryUsage: 0.3,
+    }
+});
+```
+
+As a rule of thumb for when to use `addCustomCallEvent` and `addExtensionStateEvent`:
+- Use `addCustomCallEvent` for events that are related to the call itself, such as user clicked a button.
+- Use `addExtensionStats` for events that are related to the client's environment, such as CPU usage and collected periodically.
+
+
+## Sampling
+
+The monitor generates samples by invoking the `monitor.sample()` method. The monitor will automatically call the `sample()` method unless `samplingTick` is set to a value less than or equal to 0. The ClientMonitor creates a `ClientSample`, a compound object that contains all observed stats and created events. The ClientSample object is emitted, and an event listener can listen to it by subscribing to the `sample-created` event:
+
+```javascript
+monitor.on('sample-created', ({
+    clientSample,
+    elapsedSinceLastSampleInMs,
+}) => {
+    console.log('The created client sample is:', clientSample);
+    console.log('Elapsed time in milliseconds since the last sample was created:', elapsedSinceLastSampleInMs);
+})
+```
+
+The ClientSample can be forwarded to a backend service, where the samples can be further processed (e.g., saved into a database or used for anomaly detection). To facilitate this, we have developed the [observer-js](https://github.com/ObserveRTC/observer-js) library, which you can use to process the samples.
+
+
+
 ## NPM package
 
 https://www.npmjs.com/package/@observertc/client-monitor-js

package/lib/ClientMonitor.d.ts

@@ -42,6 +42,7 @@ export interface ClientMonitorEvents {
 }
 export declare class ClientMonitor extends TypedEventEmitter<ClientMonitorEvents> {
     private _config;
+    readonly created: number;
     readonly meta: ClientMetaData;
     readonly storage: StatsStorage;
     readonly collectors: {
@@ -98,6 +99,8 @@ export declare class ClientMonitor extends TypedEventEmitter<ClientMonitorEvents
     private readonly _detectors;
     private readonly _sampler;
     private _timer?;
+    private _joined;
+    private _left;
     private _lastCollectedAt;
     private _lastSampledAt;
     private _closed;
@@ -107,6 +110,8 @@ export declare class ClientMonitor extends TypedEventEmitter<ClientMonitorEvents
     close(): void;
     collect(): Promise<CollectedStats>;
     sample(): ClientSample | undefined;
+    join(settings?: Pick<CustomCallEvent, 'attachments' | 'timestamp' | 'message'>): void;
+    leave(settings?: Pick<CustomCallEvent, 'attachments' | 'timestamp' | 'message'>): void;
     setMarker(value?: string): void;
     setMediaDevices(...devices: MediaDevice[]): void;
     addUserMediaError(err: unknown): void;

package/lib/ClientMonitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClientMonitor.d.ts","sourceRoot":"","sources":["../src/ClientMonitor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ClientMonitor.d.ts","sourceRoot":"","sources":["../src/ClientMonitor.ts"],"names":[],"mappings":"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"}