WebRTC C SDK 的客户端指标 - Kinesis Video Streams
信令指标WebRTC C SDK 支持 W3C 标准指标
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

WebRTC C SDK 的客户端指标

使用 Amazon Kinesis Video Streams with WebRTC 构建的应用程序由各种移动部件组成，包括网络、信号、候选交换、对等连接和数据交换。C 语言版 Kinesis Video Streams with WebRTC 支持各种客户端指标，使您能够监控和跟踪这些组件在应用程序中的性能和使用情况。支持的指标分为两大类：专为 Kinesis Video Streams 实现信令和网络而定义的自定义指标，以及源自 W3C 标准的媒体和数据相关协议特定指标。请注意，C 语言版 Kinesis Video Streams with WebRTC 目前仅支持 W3C 标准指标的子集

信令指标

信令指标可用于了解信令客户端在应用程序运行时的行为。您可以使用 STATUS signalingClientGetMetrics (SIGNALING_CLIENT_HANDLE, PSignalingClientMetrics)API 获取这些信令指标。下面是一个示例使用模式：

SIGNALING_CLIENT_HANDLE signalingClientHandle;
SignalingClientMetrics signalingClientMetrics;
STATUS retStatus = signalingClientGetMetrics(signalingClientHandle, &signalingClientMetrics);
printf("Signaling client connection duration: %" PRIu64 " ms",
       (signalingClientMetrics.signalingClientStats.connectionDuration / HUNDREDS_OF_NANOS_IN_A_MILLISECOND));

signalingClientStats 的定义可以在 Stats.h 中找到。

目前支持以下信令指标：

指标 描述
cpApiCallLatency 计算控制面板 API 调用的延迟。使用指数移动平均线 (EMA) 进行计算。相关的调用包括：describeChannel、createChannel、getChannelEndpoint 和 deleteChannel。
dpApiCallLatency 计算数据面板 API 调用的延迟。使用指数移动平均线 (EMA) 进行计算。相关的调用包括：getIceConfig。
signalingClientUptime 这表示客户端对象存在的时间。每次调用此指标时，都会发出最新的正常运行时间值。
connectionDuration 如果连接已建立，则会发出连接处于活动状态的持续时间。否则，会发出值为 0。这与信令客户端正常运行时间不同，因为连接断断续续，但是 signalingClientUptime 表示客户端对象本身。
numberOfMessagesSent 当对等设备发送提议、应答或 ICE 候选项时，此值会更新。
numberOfMessagesReceived 与 numberOfMessagesSent 不同，此指标会针对任何类型的信令消息进行更新。信令消息的类型可在 SIGNALING_MESSAGE_TYPE中找到。
iceRefreshCount 当调用 getIceConfig 时，该值会递增。它的调用速率基于收到的 ICE 配置中的 TTL。每次收到一组新的 ICE 配置时，都会将计时器设置为下次刷新，前提是配置中凭证的有效期减去一段宽限期。
numberOfErrors 该计数器用于跟踪信令客户端中生成的错误数量。跟踪在获取 ICE 配置、获取信令状态、跟踪信令指标、发送信令消息以及将信令客户端连接到 web 套接字以发送/接收消息时产生的错误。
numberOfRuntimeErrors 该指标包括信令客户端核心运行时发生的错误。此处跟踪重新连接失败、消息接收失败和 ICE 配置刷新错误等情况。
numberOfReconnects 该指标在每次重新连接时都会递增。该指标有助于了解设置中网络连接的稳定性。

WebRTC C SDK 支持 W3C 标准指标

使用 WebRTC C SDK 构建的应用程序目前支持 W3C 标准指标的子集。这些指标为以下类别：

  • 联网：

    • ICE 候选项：这些指标提供有关选定的本地和远程候选项的信息，以便在对等设备之间进行数据交换。这包括候选项的服务器来源、IP 地址、为通信选择的候选类型和候选优先级。这些指标可用作快照报告。

    • ICE 服务器：这些指标用于收集有关支持的不同 ICE 服务器的操作信息。这有助于尝试了解主要用于通信和连接检查的服务器。在某些情况下，如果候选项收集失败，则将有助于检查这些指标。

    • ICE 候选对：这些指标用于了解对等设备之间交换的字节/数据包的数量以及与时间相关的测量值。

  • 媒体和数据：

    • 远程入站 RTP：这些指标代表发送方发送的数据流的端点视角。

    • 出站 RTP：这些指标提供有关传出 RTP 流的信息。在分析不连贯的流或流停止时，它们也非常有用。

    • 入站 RTP：这些指标提供有关传入媒体的信息。

    • 数据通道指标：这些指标可以帮助您分析通过数据通道发送和接收的消息和字节数。可以使用通道 ID 提取指标。

您可以使用 STATUS rtcPeerConnectionGetMetrics (PRtcPeerConnection, PRtcRtpTransceiver, PRtcStats)API 收集与 ICE、RTP 和数据通道相关的指标。下面是一个用法示例：

RtcStats rtcStats;
rtcStats.requestedTypeOfStats = RTC_STATS_TYPE_LOCAL_CANDIDATE;
STATUS retStatus = rtcPeerConnectionGetMetrics (pRtcPeerConnection, NULL, &rtcStats);
printf(“Local Candidate address: %s\n”, rtcStats.rtcStatsObject.localIceCandidateStats.address);

以下是另一个示例，展示了获取收发器相关统计数据的使用模式：

RtcStats rtcStats;
PRtcRtpTransceiver pVideoRtcRtpTransceiver;
rtcStats.requestedTypeOfStats = RTC_STATS_TYPE_OUTBOUND_RTP;
STATUS retStatus = rtcPeerConnectionGetMetrics (pRtcPeerConnection, pVideoRtcRtpTransceiver, &rtcStats);
printf(“Number of packets discarded on send: %s\n”, rtcStats.rtcStatsObject.outboundRtpStreamStats.packetsDiscardedOnSend);

在上面的示例中，如果 rtcPeerConnectionGetMetrics() 的第二个参数为 NULL，则返回列表中第一个收发器的数据。

rtcStatsObject 的定义可以在 Stats.h 中找到，RtcStats 的定义可以在 Include.h 中找到。

在 WebRTC C SDK 存储库的示例目录和 Kinesis Video Stream 演示存储库中可以找到这些 API 的示例用法和不同指标。

使用 WebRTC C SDK 构建的应用程序目前支持以下 W3C 标准指标。

联网

ICE 服务器指标：

指标 描述
URL 正在追踪的 STUN/TURN 服务器的网址
端口 客户端使用的端口号
协议 从 ICE 服务器 URI 中提取的传输协议。如果值为 UDP，ICE 会通过 UDP 尝试 TURN，否则 ICE 会通过 TCP/TLS 尝试 TURN。如果 URI 不包含传输，ICE 会通过 UDP 和 TCP/TLS 尝试 TURN。如果是 STUN 服务器，此字段为空。
发送的请求总数 每个 srflx 候选请求以及从 TURN 候选项发送绑定请求时，该值都会更新。
收到的回复总数 每次收到 STUN 绑定响应时，该值都会更新。
往返总时间 每次收到请求的等效响应时，该值都会更新。在以校验和为密钥的哈希映射中跟踪请求数据包。

ICE 候选项统计信息：仅包括有关所选候选项（本地和远程）的信息。

指标 描述
address 表示本地和远程候选的 IP 地址。
port (远程调试端口) 候选端口号
protocol 用于获取候选项的协议。有效值为 UDP/TCP。
candidateType 所选候选项的类型 - 主机、srflx 或中继。
priority 所选本地和远程候选项的优先级。
url 所选本地候选项的来源。这表明所选候选项是从 STUN 服务器还是 TURN 服务器接收。
relayProtocol 如果使用 TURN 服务器来获取选定的本地候选项，则此字段表示使用了哪种协议来获取它。有效值为 TCP/UDP。

ICE 候选对统计信息：仅包含有关所选候选对的信息。

指标 描述
localCandidateId 配对中所选本地候选项的 ID。
remoteCandidateId 配对中所选远程候选项的 ID。
state 正在检查的候选对状态。
nominated 设置为 TRUE，因为正在提取选定候选对的统计信息。
packetsSent 发送的数据包数。这是在 .调用中的 writeFrame调用中计算得出的。这些信息也可以从传出的 RTP 统计数据中提取，但是由于 ICE 候选对包含 lastPacketSent 时间戳，因此计算两个时间点之间发送的数据包数量可能会很有用。
packetsReceived 每次调用 incomingDataHandler 时都会更新此信息。
bytesSent 这是在 writeFrame()调用 iceAgentSendPacket()中计算得出的。这在计算比特率时很有用。当前，这还包括标头和填充，因为 ICE 层忽略了 RTP 数据包格式。
bytesReceived 每次调用 incomingDataHandler 时都会更新此信息。当前，这还包括标头和填充，因为 ICE 层忽略了 RTP 数据包格式。
lastPacketSentTimestamp 每次发送数据包时都会更新此信息。它可以与 packetsSent 和记录的开始时间结合使用，应用于当前数据包传输速率。
lastPacketReceivedTimestamp 在 incomingDataHandler()中接收数据时更新此信息。可以与 packetsReceived 结合使用来推断当前的数据包接收速率。开始时间必须记录在应用程序层的 transceiverOnFrame()回调中。
firstRequestTimestamp 当第一个 STUN 绑定请求在 iceAgentSendStunPacket()中成功发出时记录此信息。它可以与 lastRequestTimestamp 和 requestsSent 一起使用，以查找 STUN 绑定请求之间的平均时间。
lastRequestTimestamp 每次 STUN 绑定请求在 iceAgentSendStunPacket()中成功发出时都会记录此信息。
lastResponseTimestamp 每次收到 STUN 绑定响应时都会记录此信息。
totalRoundTripTime 在收到请求的绑定响应时更新。请求和响应根据校验和映射到哈希表中。
currentRoundTripTime 当收到有关候选对请求的绑定响应时，最新的往返时间会更新。
requestsReceived 在收到每个 STUN 绑定请求时，该计数器都会更新。
requestsSent 在 iceAgentSendStunPacket()中发出每个 STUN 绑定请求时，该计数器都会更新。
responsesSent 在 handleStunPacket()中为响应绑定请求而发出每个 STUN 绑定响应时，该计数器都会更新。
responsesReceived 在 handleStunPacket()中收到每个 STUN 绑定响应时，该计数器都会更新。
packetsDiscardedOnSend 数据包发送失败时更新。换句话说，它会在 iceUtilsSendData()失败时更新。这有助于确定在特定持续时间内丢弃的数据包的百分比。
bytesDiscardedOnSend 数据包发送失败时更新。换句话说，它会在 iceUtilsSendData()失败时更新。这在确定特定持续时间内丢弃的数据包的百分比时很有用。请注意，计数器还包括数据包的标头。

媒体

出站 RTP 统计信息

指标 描述
voiceActivityFlag 这目前是 Include.h 中定义的 RtcEncoderStats的组成部分 如果最后一个音频数据包包含语音，则该标志设置为 TRUE。样本中目前未设置该标志。
packetsSent 这表示为选定的 SSRC 发送的 RTP 数据包总数。这是 https://www.w3.org/TR/webrtc-stats/#sentrtpstats-dict* 的一部分，包含在出站统计信息中。每次调用 writeFrame() 时，该值都会递增。
bytesSent 发送的总字节数，不包括 RTP 标头和填充。每次 writeFrame 调用时，该值都会更新。
encoderImplementation 它由应用程序层作为 RtcEncoderStats 对象的一部分进行更新。
packetsDiscardedOnSend 如果 ICE 代理在 iceAgentSendPacket调用中由于任何原因未能发送加密的 RTP 数据包，则会更新此字段。
bytesDiscardedOnSend 如果 ICE 代理在 iceAgentSendPacket调用中由于任何原因未能发送加密的 RTP 数据包，也会更新此字段。
framesSent 只有当媒体流堆栈类型为 MEDIA_STREAM_TRACK_KIND_VIDEO 时，该值才会递增。
hugeFramesSent 当帧大小是帧平均大小的2.5倍时，此计数器会更新。帧的大小是通过计算 fps（基于上次已知的帧计数时间和按时间间隔编码的帧数）并使用应用程序设置的 RtcEncoderStats 中的 targetBitrate 来获得。
framesEncoded 仅在成功对帧进行编码后，才会针对视频轨道更新此计数器。它会在每次 writeFrame 调用时更新。
keyFramesEncoded 仅在成功编码关键帧后，才会针对视频轨道更新此计数器。它会在每次 writeFrame 调用时更新。
framesDiscardedOnSend 当由于 iceAgentSendPacket调用失败而导致帧发送失败时，会更新此信息。一个帧由一组数据包组成，当前，如果在发送时由于错误而丢弃了任何数据包，则framesDiscardedOnSend 会失败。
frameWidth 理想情况下，这表示最后一个编码帧的帧宽。目前，该值由应用程序作为 RtcEncoderStats* 的一部分设置为一个值，意义不大。
frameHeight 理想情况下，这表示最后一个编码帧的帧高。目前，该值由应用程序作为 RtcEncoderStats 的一部分设置为一个值，意义不大。
frameBitDepth 这表示最后一个编码帧的每像素宽度的位深度。目前，该值由应用程序作为 RtcEncoderStats 的一部分设置的，并转换为出站统计信息。
nackCount 每次收到 RTP 数据包上的 NACK 并重新尝试发送该数据包时，都会更新此值。堆栈支持在收到 NACK 时重新传输数据包。
firCount 该值在收到 FIR 数据包 (onRtcpPacket->onRtcpFIRPacket) 时更新。它表示流落后且必须跳帧才能赶上的频率。目前无法解码 FIR 数据包以提取字段，因此，即使设置了计数，也不会采取任何操作。
pliCount 该值在收到 PLI 数据包 (onRtcpPacket->onRtcpPLIPacket) 时更新。它表示在一帧或多帧中丢失了一定数量的编码视频数据。
sliCount 该值将在收到 SLI 数据包 (onRtcpPacket->onRtcpSLIPacket) 时更新。它表示丢包影响单个帧的频率。
qualityLimitationResolutionChanges 目前，堆栈支持此指标，但是，并非每个编码帧的帧宽和帧高都受到监控。
lastPacketSentTimestamp 发送最后一个数据包的时间戳。它会在每次 writeFrame 调用时更新。
headerBytesSent 为此 SSRC 发送的 RTP 标头和填充字节总数，不包括实际的 RTP 有效负载。
bytesDiscardedOnSend 当由于 iceAgentSendPacket 调用失败而导致帧发送失败时，此信息会更新。帧由一组数据包组成，这些数据包又由字节组成，当前，如果在发送时由于错误而丢弃了任何数据包，bytesDiscardedOnSend 将失败。
retransmittedPacketsSent 在接收 PLI/SLI/NACK 时重新传输的数据包数量。目前，由于不支持基于 PLI 和 SLI 的重新传输，堆栈仅计算 NACK 重新发送的数据包。
retransmittedBytesSent 在接收 PLI/SLI/NACK 时重新传输的字节数。目前，由于不支持基于 PLI 和 SLI 的重新传输，堆栈仅计算 NACK 重新发送的字节数。
targetBitrate 这是在应用程序级别设置的。
totalEncodedBytesTarget 每次对帧进行编码时，目标帧大小（以字节为单位）都会增加该值。这是使用框架结构中的大小参数进行更新的。
framesPerSecond 这是根据最后一个已知编码帧的记录时间和一秒钟内发送的帧数计算得出的。
totalEncodeTime 在应用程序中将其设置为任意值，并在内部转换为出站统计信息。
totalPacketSendDelay 目前将其设置为 0，因为 iceAgentSendPacket 会立即发送数据包。

远程入站 RTP 统计信息：

指标 描述
roundTripTime 该值是从 RTCP 接收方收到类型为 201 的 RTCP 报文(接收方报告)的报告中提取的。该报告包含诸如上次发送方报告和自上次发送方报告以来的延迟等详细信息，以计算往返时间。大约每 200 毫秒生成一次发送方报告，其中包括从出站统计信息中提取的信息，例如发送的数据包数量和发送的字节数。
totalRoundTripTime 计算出的往返时间总和
fractionLost 表示自上一次发送方/接收方 reporfractionLost 发送以来 SSRC 丢失的 RTP 数据包的比例。
reportsReceived 每次收到接收方报告类型数据包时都会更新。
roundTripTimeMeasurements 表示已收到的包含有效往返时间的 SSRC 报告总数。但是，目前这个值仍是递增的，所以它的含义与 reportsReceived 相同。

入站 RTP 统计信息：

指标 描述
packetsReceived 当收到特定 SSRC 的数据包时，计数器会更新。
jitter 此指标表示特定 SSRC 的数据包抖动（以秒为单位进行衡量）。
jitterBufferDelay 该指标表示抖动缓冲区中每个数据包所花费的时间总和。
jitterBufferEmittedCount 来自抖动缓冲区的音频样本或视频帧的总数。
packetsDiscarded 当抖动缓冲区已满且无法将数据包推入其中时，计数器会更新。这可以用来计算在固定时间内丢弃的数据包的百分比。
framesDropped 当调用 onFrameDroppedFunc()时会更新此值。
lastPacketReceivedTimestamp 表示收到此 SSRC 的最后一个数据包的时间戳。
headerBytesReceived 收到 RTP 数据包后，计数器即会更新。
bytesReceived 接收的字节数。其中不包括标头字节。此指标可用于计算传入比特率。
packetsFailedDecryption 当 SRTP 数据包的解密失败时，该值会递增。

数据通道

数据通道指标

指标 描述
label 标签是正在检查的数据通道的名称。
protocol 由于我们的堆栈使用 SCTP，因此协议设置为恒定 SCTP。
dataChannelIdentifier 用于唯一标识数据通道的偶数或奇数标识符。如果 SDK 是提议者，则更新为奇数值；如果 SDK 是应答者，则更新为偶数值。
state 查询统计信息时数据通道的状态。目前，支持的两种状态是 RTC_DATA_CHANNEL_STATE_CONNECTING（通道创建时）和 RTC_DATA_CHANNEL_STATE_OPEN（在 onOpen() 事件中设置）。
messagesSent 当 SDK 通过数据通道发送消息时，计数器会更新。
bytesSent 该计数器用发送出去的消息中的字节更新。这可以用来了解有多少字节由于失败而没有发送，也就是说，可以用来了解发送的字节百分比。
messagesReceived 该指标在 onMessage()回调中递增。
bytesReceived 该指标在 onMessage()回调中生成。