Stream 通过下方描述的 GraphQL API 以及 Cloudflare 仪表板的 Stream Analytics 页面提供直播视频和上传到 Stream 的视频的分析数据。
前往 Analytics(分析) ↗Stream Analytics API 使用 Cloudflare GraphQL Analytics API,可用于许多 Cloudflare 产品。有关 GraphQL、速率限制、过滤和排序的更多信息,请参阅 Cloudflare GraphQL Analytics API 文档。
-
在 Cloudflare 仪表板中,前往 Account API tokens(账户 API 令牌) 页面。
前往 Account API tokens(账户 API 令牌) ↗ -
生成具有 Account Analytics 权限的 API token。
-
使用您选择的 GraphQL 客户端发送第一个查询。Postman ↗ 内置 GraphQL 客户端,可帮助您运行第一个查询并 introspect GraphQL schema 以了解可用功能。
以下各节介绍多个数据集中的可用指标、维度、字段和查询示例。
在 viewer.accounts 下查询 Stream 数据集。使用 filter 选择记录,并使用 dimensions 对结果分组。
分组数据集会公开 avg、sum 和 count 等聚合值。原始数据集会直接返回字段,不包含聚合对象。
带点号的字段路径表示嵌套选择:sum.minutesViewed 表示 sum { minutesViewed }。
如需查看当前字段和筛选运算符,请使用自省功能探索 GraphQL 架构。以下摘要说明了有用的字段。
Stream 会统计直播和点播视频的交付分钟数。这些数据包括通过 HLS/DASH 和 WebRTC(WHEP)交付的视频分钟数,与播放器无关。这是计费指标,但 GraphQL 数据经过抽样,因此可能与发票中报告的计费使用量不完全一致。
使用 streamMinutesViewedAdaptiveGroups 查询这些交付指标。
此数据集支持以下筛选条件和分组维度:
| 字段 | 描述 |
|---|---|
date |
日期 |
datetime |
日期和时间 |
uid |
视频 ID(适用于 HLS/DASH)或输入 ID(适用于 WebRTC/WHEP) |
clientCountryName |
观看者的 ISO 3166-1 alpha-2 国家/地区代码 |
creator |
与视频关联的创建者 ID(如果已设置) |
某些过滤器(如 date)可与 gt(大于)和 lt(小于)等运算符配合使用,如下面的示例查询所示。有关更多高级过滤选项,请参阅 过滤。
此数据集公开以下指标:
| 字段 | 描述 |
|---|---|
count |
每个维度组的值数量 |
sum.minutesViewed |
交付的视频分钟数(必须以总和形式查询) |
query StreamGetMinutesExample($accountTag: string!, $start: Date, $end: Date) {
viewer {
accounts(filter: { accountTag: $accountTag }) {
streamMinutesViewedAdaptiveGroups(
filter: { date_geq: $start, date_lt: $end }
orderBy: [sum_minutesViewed_DESC]
limit: 100
) {
sum {
minutesViewed
}
dimensions {
uid
clientCountryName
}
}
}
}
}{
"data": {
"viewer": {
"accounts": [
{
"streamMinutesViewedAdaptiveGroups": [
{
"dimensions": {
"clientCountryName": "US",
"uid": "<VIDEO_ID>"
},
"sum": {
"minutesViewed": 2234
}
},
{
"dimensions": {
"clientCountryName": "CN",
"uid": "<VIDEO_ID>"
},
"sum": {
"minutesViewed": 700
}
},
{
"dimensions": {
"clientCountryName": "IN",
"uid": "<VIDEO_ID>"
},
"sum": {
"minutesViewed": 553
}
}
]
}
]
}
},
"errors": null
}使用这些数据集检查 RTMP 或 SRT 输入。查询 liveInputEventsAdaptive 可获取事件,查询 liveInputEventsAdaptiveGroups 可获取已存储的视频片段指标。这些数据集经过抽样,因此可考虑使用 Webhook 或 Workers 事件订阅实时接收事件。
liveInputEventsAdaptive 会直接返回事件日志字段,而非视频片段指标。它会排除 eventDescription 为空的事件。
你可以选择和筛选以下字段:
| 字段 | 描述 |
|---|---|
datetime |
事件日期和时间 |
inputId |
实时输入 ID |
coloCode |
摄取数据中心代码 |
eventCode |
事件代码 |
eventDescription |
事件说明 |
liveInputEventsAdaptiveGroups 仅包含已存储视频片段的事件。它支持以下筛选条件和分组维度:
| 字段 | 描述 |
|---|---|
date |
日期 |
datetime |
日期和时间 |
eventCode |
已存储视频片段的事件代码 |
inputId |
实时输入 ID |
GOP(图像组)是一系列视频帧。“GOP 大小”有时也称为“关键帧间隔”。这些指标都与每个 GOP 的视频片段有关:
| 字段 | 描述 |
|---|---|
count |
已存储的视频片段数量 |
avg.gopUploadTime, min.gopUploadTime, max.gopUploadTime |
GOP 上传时间,单位为毫秒 |
avg.gopDuration, min.gopDuration, max.gopDuration |
GOP 时长,单位为毫秒 |
avg.gopByteSize, min.gopByteSize, max.gopByteSize |
GOP 大小,单位为字节 |
如需估算平均广播比特率,请按 inputId 和广播的 datetime 范围筛选 liveInputEventsAdaptiveGroups。在同一分组中选择 avg.gopByteSize 和 avg.gopDuration。
省略 dimensions 可获取整个广播的单个结果。例如,使用以字节为单位的 avg.gopByteSize 和以毫秒为单位的 avg.gopDuration 计算每秒比特数:
bitrate_bps = 8000 * avg.gopByteSize / avg.gopDuration两个平均值使用相同的抽样权重,因此两者的比值可用于估算总字节数除以总媒体时长。只有当 avg.gopDuration 大于零时才计算该比值。
通用媒体客户端数据(CMCD)会报告客户端播放测量数据。Stream 内置播放器和受支持的自定义播放器会提供 CMCD。
使用 streamCMCDAdaptiveGroups 查询体验质量(QoE)指标。这些测量数据描述播放器体验,不代表可计费的交付分钟数。
此数据集支持以下筛选条件和分组维度:
| 字段 | 描述 |
|---|---|
videoId |
视频 ID |
creatorId |
创建者 ID |
inputId |
实时输入 ID |
sessionId |
CMCD 会话 ID |
contentId |
内容 ID |
country |
ISO 3166-1 alpha-3 国家/地区代码,与交付指标使用的 alpha-2 代码不同 |
resolution |
视频分辨率 |
bufferStarvation |
如果上一次和当前请求之间发生缓冲停滞,则为 1;否则为 0 |
bufferStarvationDuration |
缓冲停滞时长,单位为毫秒 |
initialBufferStarvationDuration |
初始缓冲停滞时长,单位为毫秒 |
bufferLength |
所请求对象的缓冲长度 |
measuredThroughput |
客户端与服务器之间的测量吞吐量 |
streamType |
直播为 l,点播视频为 v |
encodedBitrate |
所请求对象的编码比特率 |
objectDuration |
所请求对象的时长,单位为毫秒 |
startup |
如果所请求对象为启动所需,则为 1;否则为 0 |
streamingFormat |
HLS 或低延迟 HLS(LL-HLS)为 h,DASH 为 d |
hlsType |
HLS 或 LL-HLS 为 hls 或 ll-hls,否则为空 |
topBitrate |
最高比特率的转码版本 |
playbackRate |
播放速率:实时播放为 1,两倍速为 2,未播放时为 0 |
date |
日期 |
datetime |
日期和时间 |
此数据集公开以下聚合值:
| 字段 | 描述 |
|---|---|
count |
每个维度组的值数量 |
sum.millisecondsViewed |
根据成功请求估算的观看时长,单位为毫秒 |
uniq.viewers |
仅统计成功请求中的唯一 CMCD 会话 ID,不代表唯一人数 |
avg.bufferStarvationDuration |
平均缓冲停滞时长,单位为毫秒 |
avg.initialBufferStarvationDuration |
平均初始缓冲停滞时长,单位为毫秒 |
avg.bufferLength |
平均缓冲长度 |
avg.encodedBitrate |
平均编码比特率 |
avg.measuredThroughput |
平均测量吞吐量 |
max.latestDatetime |
最后一次看到该维度组合的时间 |
在 quantiles 下选择百分位字段。所有时长的单位均为毫秒;P999 表示第 99.9 百分位:
| 字段 | 描述 |
|---|---|
bufferStarvationDurationP25 |
缓冲停滞时长的第 25 百分位 |
bufferStarvationDurationP50 |
缓冲停滞时长的第 50 百分位 |
bufferStarvationDurationP75 |
缓冲停滞时长的第 75 百分位 |
bufferStarvationDurationP90 |
缓冲停滞时长的第 90 百分位 |
bufferStarvationDurationP95 |
缓冲停滞时长的第 95 百分位 |
bufferStarvationDurationP99 |
缓冲停滞时长的第 99 百分位 |
bufferStarvationDurationP999 |
缓冲停滞时长的第 99.9 百分位 |
initialBufferStarvationDurationP25 |
初始缓冲停滞时长的第 25 百分位 |
initialBufferStarvationDurationP50 |
初始缓冲停滞时长的第 50 百分位 |
initialBufferStarvationDurationP75 |
初始缓冲停滞时长的第 75 百分位 |
initialBufferStarvationDurationP90 |
初始缓冲停滞时长的第 90 百分位 |
initialBufferStarvationDurationP95 |
初始缓冲停滞时长的第 95 百分位 |
initialBufferStarvationDurationP99 |
初始缓冲停滞时长的第 99 百分位 |
initialBufferStarvationDurationP999 |
初始缓冲停滞时长的第 99.9 百分位 |
使用 streamWHIPBroadcastMetricsAdaptive 和 streamWHIPBroadcastMetricsAdaptiveGroups 检查 WebRTC-HTTP 摄取协议(WHIP)输入。如需查看 WebRTC-HTTP 输出协议(WHEP)的播放数据,请查询交付分钟数。
Stream 每 15 秒收集一次 WHIP 观测数据。这些数据可能需要 2 到 3 分钟才能供查询。
streamWHIPBroadcastMetricsAdaptive 会直接返回以下字段。你也可以在筛选条件中使用这些字段:
| 字段 | 描述 |
|---|---|
sampleInterval |
自适应抽样间隔,而非观测时长 |
datetime |
观测日期和时间 |
inputId |
实时输入 ID |
peerConnectionState |
对等连接状态 |
iceConnectionState |
交互式连接建立(ICE)连接状态 |
trackIngestState |
轨道输入状态 |
codecName |
编解码器名称 |
codecMimeType |
编解码器媒体类型 |
peerConnectionId |
对等连接 ID |
trackId |
轨道 ID |
mediaKind |
audio 或 video |
receivedBytes |
观测期间接收的字节数 |
receivedPackets |
观察期间接收的实时传输协议(RTP)数据包 |
droppedPackets |
观察期间从摄取缓冲区丢弃的 RTP 数据包,并非全部网络丢包 |
observationDurationSeconds |
观察时长(秒) |
streamWHIPBroadcastMetricsAdaptiveGroups 支持以下筛选器和分组维度:
| 字段 | 描述 |
|---|---|
date |
日期 |
datetime |
日期和时间 |
sampleInterval |
自适应采样间隔 |
inputId |
实时输入 ID |
peerConnectionState |
对等连接状态 |
iceConnectionState |
ICE 连接状态 |
trackIngestState |
轨道输入状态 |
codecName |
编解码器名称 |
codecMimeType |
编解码器媒体类型 |
peerConnectionId |
对等连接 ID |
trackId |
轨道 ID |
mediaKind |
audio 或 video |
分组数据集公开以下指标。直接选择 count,并选择 sum 或 avg 下的嵌套字段:
| 字段 | 描述 |
|---|---|
count |
估算的观察次数 |
sum.receivedBytes |
估算的接收字节总数 |
sum.receivedPackets |
估算的接收 RTP 数据包总数 |
sum.droppedPackets |
估算的从摄取缓冲区丢弃的 RTP 数据包总数 |
sum.observationDurationSeconds |
估算的观察总时长(秒) |
avg.sampleInterval |
平均自适应采样间隔 |
avg.ingestBitrate |
接收的 bit 数除以观察秒数,单位为 bit/s |
avg.ingestPacketRate |
摄取数据包速率,单位为数据包/秒 |
GraphQL API 支持 seek 分页:使用过滤器,您可以指定最后一个 video UID,使响应仅包含该 video UID 之后的视频数据。
查询返回 $uId 之后的两个视频的数据。将 $uId 设置为上一个响应中最后一个视频的 UID:
query StreamPaginationExample(
$accountTag: string!
$start: Date
$end: Date
$uId: string
) {
viewer {
accounts(filter: { accountTag: $accountTag }) {
streamMinutesViewedAdaptiveGroups(
filter: { date_geq: $start, date_lt: $end, uid_gt: $uId }
orderBy: [uid_ASC]
limit: 2
) {
count
sum {
minutesViewed
}
dimensions {
uid
}
}
}
}
}实现分页的步骤:
- 调用第一个查询(不带 uid_gt 过滤器)以获取第一组视频
- 从第一个查询的响应中获取最后一个 video UID
- 调用下一个查询,指定 uid_gt 属性并将其设为最后一个 video UID。这将返回下一组视频
有关分页的更多信息,请参阅 Cloudflare GraphQL Analytics API 文档。
查询间隔和保留期限具有数据集特定的默认值:
| 数据集 | 最大查询间隔 | 数据保留期限 |
|---|---|---|
streamMinutesViewedAdaptiveGroups |
32 天(768 小时) | 92 天(2,208 小时) |
liveInputEventsAdaptive |
30 天 | 31 天 |
liveInputEventsAdaptiveGroups |
30 天 | 31 天 |
streamCMCDAdaptiveGroups |
30 天 | 31 天 |
streamWHIPBroadcastMetricsAdaptive |
30 天 | 30 天 |
streamWHIPBroadcastMetricsAdaptiveGroups |
30 天 | 30 天 |
使用 viewer.accounts 下的设置节点检查账户的限制。maxDuration 和 notOlderThan 字段以秒为单位报告查询间隔和保留期限。