RTCTransportStats
The RTCTransportStats
dictionary of the WebRTC API provides information about the transport (RTCDtlsTransport
and its underlying RTCIceTransport
) used by a particular candidate pair.
The BUNDLE feature is an SDP extension that allows negotiation to use a single transport for sending and receiving media described by multiple SDP media descriptions.
If the remote endpoint is aware of this feature, all MediaStreamTrack
and data channels are bundled onto a single transport at the completion of negotiation.
This is true for current browsers, but if connecting to an older endpoint that is not BUNDLE-aware, then separate transports might be used for different media.
The policy to use in the negotiation is configured in the RTCPeerConnection
constructor.
These statistics can be obtained by iterating the RTCStatsReport
returned by RTCPeerConnection.getStats()
until you find a report with the type
of transport
.
Instance properties
bytesReceived
Optional-
The total number of payload bytes received on this transport (bytes received, not including headers, padding or ICE connectivity checks).
bytesSent
Optional-
The total number of payload bytes sent on this transport (bytes sent, not including headers, padding or ICE connectivity checks).
dtlsCipher
Optional-
A string indicating the name of the cipher suite used for the DTLS transport, as defined in the "Description" column of the TLS Cipher Suites section in the IANA cipher suite registry. For example
"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"
. dtlsRole
Optional Experimental-
The DTLS role of the associated
RTCPeerConnection
. This is one of:client
server
unknown
(before the DTLS negotiation starts).
dtlsState
-
A string indicating the current
state
of the underlyingRTCDtlsTransport
. This is one of: iceLocalUsernameFragment
Optional Experimental-
A string indicating the local username fragment used in message validation procedures for this transport. This is the same value as the local
RTCIceCandidate.usernameFragment
, and will change if the connection is renegotiated. iceRole
Optional Experimental-
A string indicating the ICE
role
of the underlyingRTCDtlsTransport.iceTransport
. This is one of: iceState
Optional Experimental-
A string indicating the current
state
of the underlyingRTCIceTransport
. This is one of: selectedCandidatePairId
Optional-
A string containing the unique identifier for the object that was inspected to produce the
RTCIceCandidatePairStats
associated with this transport. localCertificateId
Optional-
A string containing the id of the local certificate used by this transport. Only present for DTLS transports, and after DTLS has been negotiated.
packetsSent
Optional Experimental-
The total number of packets sent over this transport.
packetsReceived
Optional Experimental-
The total number of packets received on this transport.
remoteCertificateId
Optional-
A string containing the id or the remote certificate used by this transport. Only present for DTLS transports, and after DTLS has been negotiated.
selectedCandidatePairChanges
Optional-
The number of times that the selected candidate pair of this transport has changed. The value is initially zero and increases whenever a candidate pair selected or lost.
srtpCipher
Optional-
A string indicating the descriptive name of the protection profile used for the Secure Real-time Transport Protocol (SRTP) transport, as defined in the "Profile" column of the IANA DTLS-SRTP protection profile registry and RFC5764.
For example
"AES_CM_128_HMAC_SHA1_80"
specifies the following profile, wheremaximum_lifetime
is the maximum number of packets that can be protected by a single set of keys.SRTP_AES128_CM_HMAC_SHA1_80 cipher: AES_128_CM cipher_key_length: 128 cipher_salt_length: 112 maximum_lifetime: 2^31 auth_function: HMAC-SHA1 auth_key_length: 160 auth_tag_length: 80
tlsVersion
Optional-
A string containing the negotiated TLS version. This is present for DTLS transports, and only exists after DTLS has been negotiated.
The value comes from the DTLS handshake
ServerHello.version
, and is represented as four upper case hexadecimal digits, where the digits represent the two bytes of the version. Note however that the bytes might not map directly to version numbers. For example, DTLS represents version 1.2 as'FEFD'
which numerically is{254, 253}
.
Common instance properties
The following properties are common to all WebRTC statistics objects.
id
-
A string that uniquely identifies the object that is being monitored to produce this set of statistics.
timestamp
-
A
DOMHighResTimeStamp
object indicating the time at which the sample was taken for this statistics object. type
-
A string with the value
"transport"
, indicating the type of statistics that the object contains.
Examples
This example shows a function to return the transport statistics, or null
if no statistics are provided.
The function waits for the result of a call to RTCPeerConnection.getStats()
and then iterates the returned RTCStatsReport
to get just the stats of type "transport"
.
It then returns the statistics, or null
, using the data in the report.
async function numberOpenConnections (peerConnection) {
const stats = await peerConnection.getStats();
let transportStats = null;
stats.forEach((report) => {
if (report.type === "transport") {
transportStats = report;
break;
}
});
return transportStats
}
Specifications
Specification |
---|
Identifiers for WebRTC's Statistics API # dom-rtcstatstype-transport |
Browser compatibility
BCD tables only load in the browser