Diagnostics
Take a diagnostic bundle while a problem is happening or soon afterwards. It compares the encoder, network and client over the same period to identify the likely cause.
Taking one
Section titled “Taking one”- Open the session in Admin ▸ Sessions.
- Download its diagnostic bundle.
- Read the verdict below, then use Stream quality for the next checks.
With an admin token, you can also download it directly:
curl -s "https://<host>:8443/v1/admin/sessions/<session-id>/diagnostic-bundle" \ -H "Authorization: Bearer $TOKEN" > bundle.jsonThe window defaults to five minutes (range two to ten).
Take it soon: a running session keeps one hour of telemetry, and an ended one keeps it for 24 hours by default.
What is in one
Section titled “What is in one”| Part | Contents |
|---|---|
| Metrics | Encode time, frame rate, ABR setpoint, round trip time, packet loss, client presentation variation. |
| Events | Bitrate retargets, freezes, WebRTC state changes, playout buffer changes. |
| Clock alignment | Host-to-browser clock offset. If unmeasured, end-to-end latency figures aren’t trustworthy. |
| Derived windows | Hitches, bitrate downshifts, encoder saturation, likely congestion. |
| Verdict | See below, with a short list of evidence. |
Reading the verdict
Section titled “Reading the verdict”| Verdict | Meaning |
|---|---|
nominal |
Nothing wrong found, tab visible. |
likely_network_congestion |
Loss and round trip time rose with a bitrate downshift. |
likely_encoder_saturation |
Encode time at or above the ceiling while frame rate was steady. |
likely_client_presentation_limit |
The client presented frames unevenly; encode and network looked clean. |
indeterminate_client_hidden |
The browser tab was hidden. Reproduce with it visible and take another bundle. |
unknown |
Doesn’t fit the cases above. |
The verdict is informational; nothing acts on it. New values may appear.
The thresholds it uses
Section titled “The thresholds it uses”| Signal | Threshold |
|---|---|
| Encode time, 95th percentile | 16 ms and above is saturation |
| Presentation interval variation | 18 ms and above contributes to a hitch (after warm-up, repeated) |
| Round trip time, 95th percentile | above 50 ms contributes to congestion |
| Cumulative packet loss rise | above 5 packets contributes to congestion |
| Host frame rate, 10th percentile | below 50 fps means the encoder is not steady |
Annotations
Section titled “Annotations”You can add a note to a session’s timeline. Annotate a mid-session setting change so it shows up next to its effect in the bundle.
Comparing two runs
Section titled “Comparing two runs”There is no built-in comparison. Take a bundle for each and change exactly one thing: same app, tier, client, network and similar content.
GPU fault messages in session traces
Section titled “GPU fault messages in session traces”Optional. With it, the agent reads GPU fault messages from the kernel log and
attaches them to running sessions’ traces: NVIDIA Xid errors and AMD amdgpu ring
timeouts (Intel isn’t covered). Without it, the xid_visibility readiness check
reads skipped, and you read dmesg yourself.
It is off by default for a reason: it lets every account on the machine read the whole kernel log. Turn it on only where that’s acceptable.
What to do, on the GPU host:
echo 'kernel.dmesg_restrict=0' | sudo tee /etc/sysctl.d/99-quasar-kernel-log.confsudo sysctl -w kernel.dmesg_restrict=0Check it worked: sysctl kernel.dmesg_restrict prints 0, and the host’s
xid_visibility check no longer reads skipped.
To turn it off: delete that file and run sudo sysctl -w kernel.dmesg_restrict=1.
What to attach to a bug report
Section titled “What to attach to a bug report”For a session problem, the diagnostic bundle. For install or startup problems, a redacted state dump from a checkout:
make diagnose-bundle