Client Reports

Client Reports are complex objects that are specific to the technology that was used to measure the data.

We provide them so you can dig deeper into the data and analyze it in more detail.

Each Client Report contains:

• metadata (e.g., the type and timestamp) common to all Client Reports
• the actual data that was measured by the client

Normally, each measured subject has its own type of Client Report. For example:

• A video study with subject youtube has a YoutubeClientReport
• A network study with subject dns has a DnsClientReport
• … and so on

However, there are also some generic Client Reports that can be used for multiple services:

• Each video study has a P1203ClientReport which contains information about the video quality and a PerformanceClientReport which contains information about the performance of the playback.

Finally, some services could have multiple types of Client Reports (e.g., YouTube has a Client Report for its Stats for Nerds, but we might add more in the future). In the latter case, the data_type attribute may identify the specific type of the Client Report.

Example

Here is are two example Client Reports, both for a video measurement (as identified by the measurement_id):

P.1203 Client ReportYouTube Client Report

We provide this one for every video measurement. This corresponds to the input format of the P.1203 video QoE model. It allows you to get a good overview of what happened during a streaming session.

{
  "id": 43009,
  "measurement_id": 874,
  "type": "P1203ClientReport",
  "data_type": "object",
  "created_at": "2023-02-11T13:42:58.510Z",
  "updated_at": "2023-02-11T13:42:58.510Z",
  "client_time": "2023-02-11T13:42:54.875Z",
  "client_time_skewed": "2023-02-11T13:42:54.878Z",
  "data": {
    "I11": {
      "segments": [
        {
          "codec": "opus",
          "start": 0,
          "bitrate": 125.36497312878555,
          "duration": 0.6666666666666666
        },
        {
          "codec": "opus",
          "start": 0.6666666666666666,
          "bitrate": 125.36497312878555,
          "duration": 19.333333333333332
        },
        {
          "codec": "opus",
          "start": 20,
          "bitrate": 127.71297482399984,
          "duration": 20.333333333333332
        },
        {
          "codec": "opus",
          "start": 40.333333333333336,
          "bitrate": 133.1045843559189,
          "duration": 19
        }
      ],
      "streamId": 1
    },
    "I13": {
      "segments": [
        {
          "fps": 25,
          "codec": "vp9",
          "start": 0,
          "bitrate": 296.51000006291014,
          "duration": 0.6666666666666666,
          "resolution": "640x360"
        },
        {
          "fps": 29.666666666666668,
          "codec": "vp9",
          "start": 0.6666666666666666,
          "bitrate": 296.51000006291014,
          "duration": 19.333333333333332,
          "resolution": "854x480"
        },
        {
          "fps": 51,
          "codec": "vp9",
          "start": 20,
          "bitrate": 2516.2002482479243,
          "duration": 20.333333333333332,
          "resolution": "1920x1080"
        },
        {
          "fps": 61,
          "codec": "vp9",
          "start": 40.333333333333336,
          "bitrate": 2401.3066847336336,
          "duration": 19,
          "resolution": "1920x1080"
        }
      ],
      "streamId": 1
    },
    "I23": {
      "pauses": [
        [
          0.513657,
          0.068
        ],
        [
          0.591163,
          0.035
        ],
        [
          0.674196,
          0.05
        ],
        [
          0.702526,
          0.009
        ],
        [
          0.768459,
          0.003
        ]
      ],
      "stalling": [
        [
          0,
          0.901
        ]
      ],
      "streamId": 1
    },
    "IGen": {
      "device": "pc",
      "displaySize": "1920x1080",
      "viewingDistance": "150cm"
    }
  }
}

1. This is a P1203ClientReport data type (see below for its definition).

This is a Client Report for a YouTube video measurement. It contains the Stats for Nerds data that YouTube provides for each video. This is a very detailed report that allows you to analyze the video quality in great detail.

Note that the data type is stats_for_nerds, as we might add more YouTube Client Reports in the future.

{
    "id": 43008,
    "measurement_id": 874,
    "type": "YoutubeClientReport",
    "data_type": "stats_for_nerds",
    "created_at": "2023-02-11T13:42:58.502Z",
    "updated_at": "2023-02-11T13:42:58.502Z",
    "client_time": "2023-02-11T13:42:54.332Z",
    "client_time_skewed": "2023-02-11T13:42:54.335Z",
    "data": { // (1)!
        "s_cpn": "BBGW T4J4 V8DK",
        "volume": 100,
        "video_id": "aqz-KE-bpKQ",
        "viewport": "1920x1080",
        "timestamp": "Sat Feb 11 2023 13:42:53 GMT+0000 (Coordinated Universal Time)",
        "audio_itag": 251,
        "video_itag": 303,
        "color_space": "bt709",
        "current_fps": 60,
        "current_res": "1920x1080",
        "optimal_fps": 60,
        "optimal_res": "1920x1080",
        "frames_total": 2747,
        "mystery_text": "s:8 t:58.36 b:0.000-99.733 L pbs:1562",
        "buffer_health": 41.55,
        "frames_dropped": 2,
        "audio_codec_mime": "opus",
        "connection_speed": 69076,
        "content_loudness": -4.7,
        "network_activity": 1680,
        "video_codec_mime": "vp09.00.51.08.01.01.01.01.00",
        "normalized_volume": 100
    }
}

1. This is a YoutubeStatsForNerdsInfo data type (see below for its definition).

Properties

Common Properties

General attributes for a client report.

Property	Type	Description
clientTime	string, or number	The time at which the report was created
clientTimeSkewed	string, or number (optional)	The time at which the report was created, adjusted in case of client skew
data	object (no predefined properties)	The actual client report data
dataType	array of string	The type of data (if not explicitly defined, simply 'object')
type	array of string	The type of client report

Data Properties

ByteCountClientReport Data

A report for storing byte counts for a given measurement session.

Property	Type	Description
byteCounts	array of array	The byte counts, as a tuple of timestamp and bytes

DnsClientReport Data

A report for dig-based DNS measurements.

Property	Type	Description
answerIp	string	The resolved IP for the host, as returned by the DNS server (may be IPv4 or IPv6)
avgQueryTime	number	Average query time in microseconds
host	string	The host that was queried (multiple client reports will be used for multiple hosts)
individiualQueryTimes	array of number	Individual query times in microseconds
maxQueryTime	number	The maximum query time in microseconds
nameserver	string	The used nameserver for this request, may be empty if useGetAddrInfo was used for the study

IcmpPingClientReport Data

A report for ping-based ICMP measurements.

Property	Type	Description
avgRtt	number	The average round-trip time (in milliseconds)
dataBytes	number	The number of bytes of data sent in each ping
host	string	The host that was pinged
individualPings	array of object (optional)	An array of individual ping results
ipAddress	string	The IP address of the host that was pinged
maxRtt	number	The maximum round-trip time (in milliseconds)
minRtt	number	The minimum round-trip time (in milliseconds)
packetsLost	number	The packet loss percentage (from 0 to 100)
packetsReceived	number	The number of ping packets received
packetsTransmitted	number	The number of ping packets transmitted
stdevRtt	number	The standard deviation of round-trip times (in milliseconds)

LighthouseClientReport Data

A Lighthouse measurement result. Simplified type definition from the original Lighthouse project.

Property	Type	Description
audits	object (no predefined properties)	An object containing the results of the audits, keyed by the audits' id identifier.
categories	object (no predefined properties)	The top-level categories, their overall scores, and member audits.
categoryGroups	object (no predefined properties) (optional)	Descriptions of the groups referenced by CategoryMembers.
configSettings	object (no predefined properties)	The config settings used for these results.
entities	object (no predefined properties) (optional)	All the origins encountered during this Lighthouse run, and information about what web property (aka "entity") they belong to. Won't be present for snapshot mode.
environment	object (no predefined properties)	Information about the environment in which Lighthouse was run.
fetchTime	string	The ISO-8601 timestamp of when the results were generated.
finalDisplayedUrl	string	The URL displayed on the page after Lighthouse finishes.
finalUrl	string (optional)	For historical reasons, this will always be the same as mainDocumentUrl.
fullPageScreenshot	object (no predefined properties) (optional), or null (optional) (optional)	Screenshot taken of the full page, with node rects referencing audit results. If there was an error with collection, this is null. If disabled via the disableFullPageScreenshot setting, this is undefined.
gatherMode	string	Gather mode used to collect artifacts for this result.
i18n	object (no predefined properties)	Strings for the report and the record of all formatted string locations in the LHR and their corresponding source values.
lighthouseVersion	string	The version of Lighthouse with which these results were generated.
mainDocumentUrl	string (optional)	URL of the last document request during a Lighthouse navigation. Will be undefined in timespan/snapshot.
requestedUrl	string (optional)	The URL that Lighthouse initially navigated to. Will be undefined in timespan/snapshot.
runWarnings	array of string	List of top-level warnings for this Lighthouse run.
runtimeError	object with properties: code, message (optional)	A top-level error message that, if present, indicates a serious enough problem that this Lighthouse result may need to be discarded.
stackPacks	array of object (optional)	An array containing the result of all stack packs.
timing	object (no predefined properties)	Execution timings for the Lighthouse run
userAgent	string	The User-Agent string of the browser used run Lighthouse for these results.

NetflixClientReport Data

Information gathered from the Netflix player debug window. Note that in practice some data may not be available.

Property	Type	Description
audioBitrate	number	The bitrate of the audio in kbps
audioCdn	string	The domain of the CDN used to deliver the audio content
audioCodec	string	The audio codec used by the stream in MIME format, e.g. "audio/mp4; codecs=\"mp4a.40.5\" (he-aac)"
bufferingState	string	The state of the player's internal buffering
bufferingVmaf	number	The VMAF score of the stream for buffering
corruptedFrames	number	The number of corrupted frames in the stream
decodedFrames	number	The number of decoded frames in the stream
droppedFrames	number	The number of dropped frames in the stream
duration	number	The duration of the stream in seconds
framerate	number	The framerate of the stream in frames per second
playerState	string	The state of the player
playingVmaf	number	The VMAF score of the stream for playing
position	number	The position of the player in the stream in seconds
renderingState	string	The state of the player's rendering
resolution	string	The resolution of the stream
throughput	string, or number	The throughput as a string formatted as "69000 kbps" or similar, or a number in kbps (legacy)
totalFrameDelay	number, or null	The total frame delay of the stream
videoBitrate	number	The bitrate of the video in kbps
videoCdn	string	The domain of the CDN used to deliver the video content
videoCodec	string	The video codec used by the stream in MIME format, e.g. "video/mp4;codecs=vp09.00.11.08.02 (vp9)"

NetworkPerformanceClientReport Data

This report contains global and domain-specific metrics based on a set of network requests and responses.

Property	Type	Description
domainPerformance	array of object	The domain-specific metrics
firstRequestTime	string	The time of the first request in ISO 8601 format
globalMetrics	object with properties: averageRequestTime, contentTypeDistribution, totalTransferSize	The global metrics
parentDomain	string	The parent domain from which requests were made
totalRequests	number	The number of requests

OoklaSpeedtestClientReport Data

A report for Ookla Speedtest measurements made with the Ookla Speedtest CLI.

Property	Type	Description
download	object with properties: bandwidth, bytes, elapsed, latency	A single speedtest result.
interface	object with properties: externalIp, internalIp, isVpn, macAddr, name	Network interface information
isp	string	Internet Service Provider
packetLoss	number	Packet loss percentage
ping	object with properties: high, jitter, latency, low	Network ping information
result	object with properties: id, persisted, url	Test result information
server	object with properties: country, host, id, ip, location, name, port	Server information
timestamp	string	The timestamp of the report in ISO 8601 format
type	string	The type of report, should be fixed to "result"
upload	object with properties: bandwidth, bytes, elapsed, latency	A single speedtest result.

P1203ClientReport Data

P1203ClientReport is the same as P1203InputReport, but with additional options for the programmatic calculation.

Property	Type	Description
I11	object with properties: segments, streamId
I13	object with properties: segments, streamId
I23	object with properties: pauses, seeking, stalling, streamId
IGen	object with properties: device, displaySize, viewingDistance
O21	array of number (optional)
O22	array of number (optional)
calculationSettings	object with properties: amendment1App2, amendment1Audiovisual, amendment1Stalling, fastMode, pa, pq, pv, verbose (optional)

PerformanceClientReport Data

A report for video playback performance.

Property	Type	Description
audioBufferTrace	array of array (optional)	The video player audio buffer size. Each entry is a tuple of media timestamp and size in seconds.
bufferTrace	array of array	The video player buffer size. Each entry is a tuple of media timestamp and size in seconds.
droppedVideoFrames	number	The number of dropped video frames
latencyTrace	array of array	The video player latency (CDN-to-player). Each entry is a tuple of media timestamp and latency in seconds.
videoBufferTrace	array of array (optional)	The video player video buffer size. Each entry is a tuple of media timestamp and size in seconds.

TracerouteClientReport Data

A report for traceroute-based measurements.

Property	Type	Description
firstHop	object with properties: asns, hostnames, ipAddresses, rtts, seq (optional)	The first hop
host	string	The host name of the target
individualHops	array of object (optional)	An array of individual hop results
ipAddress	string	The IP address of the target
lastHop	object with properties: asns, hostnames, ipAddresses, rtts, seq (optional)	The last host
maxHops	number	Maximum number of hops used
numHops	number (optional)	The final number of hops to the target
packetSize	number	Bytes per packet

WebrtcInternalsClientReport Data

Data that can be extracted from the chrome://webrtc-internals page via download TODO: further narrow types if needed.

Property	Type	Description
PeerConnections	object (no predefined properties)
UserAgent	string
getUserMedia	array of object

YoutubeClientReport Data

An object containing the YouTube Stats for Nerds window information.

Property	Type	Description
audioCodecMime	string	The audio codec MIME type, e.g. "opus"
audioItag	number	The audio itag
bufferHealth	number	Buffer health in seconds
colorSpace	string (optional)	The color space name, e.g. "bt709". Not always fetchable, e.g. in Safari.
connectionSpeed	number	The connection speed in kbps
contentLoudness	number	The content loudness
currentFps	number	The current fps
currentRes	string	The current resolution in "<width>x<height>"
framesDropped	number	The number of dropped frames
framesTotal	number	The total number of frames
mysteryText	string	Who knows what this might be?
networkActivity	number	The current network activity in KB
normalizedVolume	number	The normalized volume
optimalFps	number	The optimal fps
optimalRes	string	The optimal resolution in "<width>x<height>"
sCPN	string	The video title
timestamp	string (optional)	An ISO 8601 timestamp
videoCodecMime	string	The video codec NIME type, e.g. "av01.0.08M.08"
videoId	string	The video ID
videoItag	number	The video itag
viewport	string	The viewport size in "<width>x<height>"
viewportScale	number	The viewport scale
volume	number	The volume