> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streampixel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnostics

> Read a Streampixel Web SDK stream's quality with stats and getDiagnostics(), see exactly what the SDK reports to Streampixel and stores in the browser, and follow a procedure to debug a bad session.

Expert For developers who debug sessions, and for privacy and security reviewers. After this page you can read every number the SDK gives you, say exactly what the SDK reports to Streampixel, and find out why one session went wrong.

There are three sources of information about a stream.

| Source | What it is | Who reads it |
| - | - | - |
| The [`stats` event](#stats-in-depth) | Quality numbers, once a second while video plays. | Your page |
| [`getDiagnostics()`](#getdiagnostics) | A snapshot of the video connection, when you ask for it. | Your page, and support |
| [Telemetry](#what-the-sdk-reports-to-streampixel) | Reports the SDK sends to Streampixel during the session. | Your dashboard's session pages, and Streampixel support |

## `stats` in depth

```ts theme={"dark"}
stream.on('stats', (s) => {
  console.log(`${s.fps} fps, ${s.bitrateKbps} kbps, ${s.resolution}, ${s.codec}, round trip ${s.latencyMs} ms`);
});
```

All values come from the browser's own WebRTC statistics for the video connection.

| When | Detail |
| - | - |
| Starts | When the video plays. |
| Interval | Every second. |
| Stops | When signalling closes or the connection is rebuilt. There are no `stats` events while the state is `reconnecting`. |
| Starts again | When video plays again after a reconnect or a recovery. The totals then count from the new connection. |

**fps** `number`

Frames decoded since the previous sample, divided by the time between the two samples, rounded.

**latencyMs** `number`

The network round-trip time of the connection in use, in milliseconds. It is the time for a packet to reach the other end and come back. It is not the time from a click to the picture changing: that also includes rendering, encoding and decoding.

`0` until the browser has a first reading. When one sample has no reading, the last good value is kept.

**framesDecoded** `number`

Total frames decoded on this connection.

**framesDropped** `number`

Total frames the browser dropped on this connection.

**bitrateKbps** `number | null`

Video received since the previous sample, in kilobits per second. Video only: sound is not counted. `null` when it cannot be computed for a sample.

**resolution** `string | null`

The size of the decoded picture, for example `"1920x1080"`. `null` until the browser reports a size.

**codec** `string | null`

The video codec in use, for example `"H264"` or `"AV1"`. `null` until the browser reports it.

**relayTransport** `'' | 'udp' | 'tcp' | 'tls'`

The transport of the relay in use. `''` on a direct path. `'tcp'` or `'tls'` means UDP is blocked on the viewer's network: see [Relay fallback](https://docs.streampixel.io/resources/web-sdk-v2/reliability.md#relay-fallback).

**avgQp** `number | null`

The encoder's quantisation parameter, as the app last reported it. It is always on H.264's scale of 0 to 51, whatever the codec. Lower means better picture quality. `null` before the first value.

**packetsLost** `number`

Video packets lost since this connection started.

**bytesReceived** `number`

Bytes received since this connection started, video and sound together.

> [!NOTE]
>
> The first sample after the video starts compares with zero. Its `fps` and `bitrateKbps` cover everything received since the connection came up, so they can read high. Skip the first sample in a chart.

The `videoEncoderAvgQP` event gives the same quantisation parameter as `avgQp`, pushed about once a second as the app reports it.

### Reading the numbers

These are the usual meanings. Treat them as a starting point, not as proof.

| What you see | What it usually means |
| - | - |
| `relayTransport` is `'tcp'` or `'tls'` | UDP is blocked on the viewer's network. The stream is relayed, at lower quality. |
| `packetsLost` keeps rising | The viewer's network loses packets. |
| `latencyMs` is high and steady | A long route between the viewer and the stream. See [Regions](https://docs.streampixel.io/resources/concepts/regions.md). |
| `avgQp` is high | The encoder compresses hard to stay within the bitrate it is allowed or the network can carry. The picture looks soft or blocky. |
| `framesDropped` keeps rising while `fps` is low | The viewer's device does not keep up with decoding. |
| `fps` falls to `0` and stays there | No frames arrive. After 10 seconds the SDK acts: see [Connected, and no video frames](https://docs.streampixel.io/resources/web-sdk-v2/reliability.md#connected-and-no-video-frames). |

How the same numbers appear in the dashboard is described in [Analytics interpretation](https://docs.streampixel.io/resources/dashboard/analytics-interpretation.md). A ready-made readout for your page is in the [cookbook](https://docs.streampixel.io/resources/web-sdk-v2/cookbook.md).

## `getDiagnostics()`

`getDiagnostics()` returns a snapshot of the video connection at this moment: its states, the network paths the browser found, and the path in use.

```ts theme={"dark"}
const snapshot = await stream.getDiagnostics();

if (snapshot) {
  console.log(snapshot.verdict);        // one sentence, for example "direct connection (SRFLX)"
  console.log(snapshot.connectionType); // 'TURN' when the stream is relayed
}
```

It resolves to `null` when there is no video connection: before the connection is negotiated, and after the session ended. Take the snapshot **while the stream is up**.

> [!WARNING]
>
> The snapshot holds the viewer's network addresses, public and local, unshortened. Give it to support. Do not publish it, and do not send it to a third-party logging service without a reason.

The `stalled` event carries the same snapshot, taken at the moment the SDK judged the video dead. Its TypeScript type lists the first nine fields below.

**verdict** `string`

One sentence that sums up the snapshot.

**every verdict**

| `verdict` | Meaning |
| - | - |
| `connection too early for stats` | The browser has no statistics yet. |
| `network blocks UDP and TURN — only host candidates gathered (corporate firewall pattern)` | The browser finished looking and found only local addresses. |
| `every candidate pair failed — path to media blocked` | Paths were found and every one of them failed. |
| `ICE stuck in checking >30s — firewall or asymmetric block` | The browser has been testing paths for more than 30 seconds. |
| `relayed via TURN (address:port)` | The stream runs through the relay. |
| `direct connection (TYPE)` | The stream runs on a direct path. |
| `gathering / negotiating` | The connection is still being set up. |

**iceConnectionState** `string`

The browser's state for the network path: `new`, `checking`, `connected`, `completed`, `disconnected`, `failed` or `closed`.

**connectionState** `string`

The browser's state for the whole video connection.

**iceGatheringState** `string`

Whether the browser is still looking for network paths: `new`, `gathering` or `complete`.

**hostCandidatesFound** `boolean`

The browser found a local address.

**srflxCandidatesFound** `boolean`

The browser found its public address. `false` together with `relayCandidatesFound: false`, after gathering is complete, is the pattern of a network that blocks the stream.

**relayCandidatesFound** `boolean`

The browser reached the relay and got an address on it.

**candidatePairs** `number`

How many pairs of addresses (one on each side) the browser has.

**connectedPairs** `number`

How many of those pairs work.

**failedPairs** `number`

How many of those pairs failed.

**connectionType** `string`

The kind of path in use: `TURN` for the relay, otherwise the type of the viewer's address on that path, such as `HOST` or `SRFLX`. Absent while no path is selected.

**selectedServer** `string`

The viewer's end of the path in use, as `address:port`. On a relayed path this is the relay's address. On a direct path it is the viewer's own address.

**issues** `string[]`

Problems the SDK detected in this snapshot. Absent when there are none.

**every issue**

| Issue | Meaning |
| - | - |
| `ICE_FAILED` | The network path failed. |
| `ICE_DISCONNECTED` | The network path is disconnected. |
| `PEER_CONNECTION_FAILED` | The video connection failed. |
| `NO_TURN` | No relay address was found, and the stream is not connected. |
| `NO_CANDIDATES` | No address of any kind was found. |
| `ALL_CANDIDATE_PAIRS_FAILED` | Every pair of addresses failed. |
| `ICE_CHECKING_TIMEOUT` | The browser has been testing paths for more than 30 seconds. |

**likelyCause** `string`

A first guess derived from `issues`: `TURN_SERVER_ISSUE`, `NETWORK_FIREWALL_ISSUE`, `SIGNALLING_SERVER_ISSUE` or `UNKNOWN_ISSUE`. Absent when there are no issues. It is a hint for where to look first, not a diagnosis.

**timeSinceStart** `number`

Milliseconds since the stream object was created.

> [accordion] The raw lists in the snapshot
>
> For support, the snapshot also carries the detail behind the summary.
>
> | Field | Content |
> | - | - |
> | `signalingState` | The browser's state for the offer and answer exchange. |
> | `statsAvailable` | Whether the browser returned statistics. |
> | `localCandidates` | The viewer's addresses: type, protocol, address, port, priority. |
> | `remoteCandidates` | The other side's addresses: type, protocol, address, port. |
> | `candidatePairsDetails` | Each pair: its state, whether it is nominated, bytes sent and received, round-trip time. |
> | `transport` | The secure transport's state, the selected pair, bytes sent and received. |
> | `inboundRtp` | The incoming video: packets received and lost, bytes, jitter, frames decoded and dropped. |
> | `turnServerUrls` | The relay addresses the browser obtained. |
> | `selectedTurn` | The relay address in use, when the stream is relayed. |

## What the SDK reports to Streampixel

This section is written for a privacy or security review.

The SDK reports to Streampixel's own telemetry service during a session. These reports are what the session pages of your dashboard show, and what Streampixel support reads when you ask about a session.

| Question | Answer |
| - | - |
| Where do the reports go? | To `https://telemetry.streampixel.io`, by HTTPS. A dedicated or on-premises deployment sets its own host with `advanced.telemetryHost`. |
| How are they authorised? | With a token the platform issues together with the session's ticket. The platform takes the project from the token, not from the page. |
| Are third parties involved? | No. The SDK contains no analytics SDK and no tracker, and it sets no cookie. |
| Can a report slow the stream? | No. Each report is sent without waiting for the answer, with a limit of 1.5 seconds. A failed report is dropped. |
| What happens when the page closes? | One last report is sent with the browser's beacon mechanism, which survives the page closing. |
| Can it be switched off? | It can be reduced, not switched off: see the two levels below. |

### Two levels

> [tab] standard (default)
>
> Everything in the table below.
>
> ```ts theme={"dark"}
> const stream = await Streampixel.create({ appId: 'YOUR_PROJECT_ID', container });
> ```

> [tab] minimal
>
> Session lifecycle only. No connection diagnostics, no statistics.
>
> ```ts highlight={4} theme={"dark"}
> const stream = await Streampixel.create({
>   appId: 'YOUR_PROJECT_ID',
>   container,
>   telemetry: 'minimal',
> });
> ```
>
> The session pages of your dashboard can then show less for these sessions, and support has less to work with.

| Category | What is reported | `standard` | `minimal` |
| - | - | - | - |
| Session lifecycle | The session starting, and how the viewer got in (public, password, single sign-on, ticket). Which engine build was loaded, from which of the two engine hosts. Every state change, with the state's own fields (queue position, reconnect attempt, end code and reason). Reconnects, recoveries, the browser going offline, the idle timeout. The session ending, with code, reason and kind. The page closing. | Yes | Yes |
| Connection diagnostics | A snapshot like `getDiagnostics()`, with the viewer's addresses shortened, at the steps of the connection (signalling connected or closed, offer, answer, connected) and at failures (a stall, a blocked network, a failed video connection). The addresses of the relay servers the platform handed out, and whether they came with credentials. Never the credentials. | Yes | No |
| Playback and capture | The video starting. The browser refusing autoplay. Whether the microphone or camera was attached, when your page or project asks for them. No sound or picture from them. | Yes | No |
| What the SDK sent to the app by itself | That the touch-device flag was sent. The project's startup console commands as they run: the first 80 characters of each, and whether it was sent. | Yes | No |
| Statistics | About once a minute, and first after about 10 seconds: frame rate, round-trip time, frames decoded and dropped, video bitrate, resolution, codec, relay transport, packet loss, data received, quantisation parameter, sound codec and bitrate, and how long the video has played. | Yes | No |

### Sent with every report

| Data | Detail |
| - | - |
| Session ID, streamer ID, project ID, the project's region | The same IDs as `stream.currentSessionId` and `stream.currentStreamerId`. |
| Operating system, browser, device class | Names only, such as "Windows", "Chrome", "desktop". The SDK derives them in the page from the browser's user agent, and puts only the names in the report. Like any web request, the request itself carries the browser's standard headers and comes from the viewer's IP address. |
| The page's origin and path | Never the query string and never the fragment, so tokens or parameters in your page's address are not reported. |
| Approximate location | Country, state and city, as the platform determined them for the connection. No coordinates and no postal code. |
| SDK version, a timestamp, the time since the session started | |

### Network addresses

The viewer's own network addresses appear in connection diagnostics. They are shortened in the page, before a report is sent:

| Address | Reported as |
| - | - |
| IPv4, for example `203.0.113.57` | The first two numbers: `203.0.x.x` |
| IPv6 | The first two groups |
| Local `.local` names that browsers use in place of local addresses | Unchanged |
| The platform's side of the connection | Unchanged |

`getDiagnostics()`, which returns to your own page, is not shortened.

### Never reported

* Passwords and tickets.
* Your `launchParams`.
* Messages between your page and your app, in either direction.
* The viewer's sound, camera picture, keyboard or mouse input.

### When nothing is reported

* Before a ticket exists. A password project that is waiting for its password has reported nothing.
* When the ticket came from your own server ("Your app only", not available yet) without its telemetry token.

### What the SDK stores in the browser

| Storage | Key | What | How long |
| - | - | - | - |
| `sessionStorage` | `spx:pw:<projectId>` | A project password the viewer entered correctly, so that a reload does not ask again. `rememberPassword: false` turns it off. | This tab |
| `sessionStorage` | `spx:sfuHost:<projectId>`, `spx:sfuHostKey:<roomId>` | A shared-session host's room ID and the key for it. | This tab |
| `localStorage` | `spx.sdk.seq` | The number of the newest engine manifest this browser has seen, so that an older one is refused. | Until cleared |

The SDK sets no cookie.

### Every connection the SDK opens

| To | For |
| - | - |
| `js.streampixel.io`, `js-backup.streampixel.io` | The engine: see [The engine and updates](https://docs.streampixel.io/resources/web-sdk-v2/engine-and-updates.md). |
| `platform.streampixel.io` | The project lookup and the session ticket. |
| A `wss://` host named in the ticket | Signalling. |
| The app's server or the relay, named during signalling | The video connection (WebRTC). |
| `telemetry.streampixel.io` | The reports described above. |
| The chat server on LiveKit Cloud | Only when your page uses [voice chat](https://docs.streampixel.io/resources/web-sdk-v2/voice-chat.md). |

The matching Content-Security-Policy is in [Installation](https://docs.streampixel.io/resources/web-sdk-v2/installation.md#content-security-policy). The ports a viewer's network must allow are in [Network requirements](https://docs.streampixel.io/resources/concepts/network-requirements.md).

## How to debug a bad session

**1. Record what happened**

Add this helper while you debug. It prints every state, event and end with the time since the start, and keeps the last minute of `stats`.

```ts debug.ts expandable theme={"dark"}
import type { Streampixel, StreamStats } from '@streampixel/web-sdk';

export function attachDebug(stream: Streampixel) {
  const t0 = Date.now();
  const lastStats: StreamStats[] = [];
  const log = (what: string, data?: unknown) =>
    console.log(`[stream +${((Date.now() - t0) / 1000).toFixed(1)} s] ${what}`, data ?? '');

  log('engine', stream.engineVersion);
  log('state', stream.state); // the state when you attached

  stream.on('session', (ids) => log('session', ids));
  stream.on('state', (s) => log(`state ${s.kind}`, s));
  stream.on('progress', ({ stage }) => log(`progress ${stage}`));
  stream.on('queue', ({ position }) => log('queue', position));
  stream.on('relayFallback', (e) => log('relayFallback', e));
  stream.on('stalled', (d) => log('stalled', d));
  stream.on('stats', (s) => {
    lastStats.push(s);
    if (lastStats.length > 60) lastStats.shift();
  });
  stream.on('ended', (e) => log('ended', { ...e, lastStats }));

  // Call this from the console, or from a "Report a problem" button, while the stream is up.
  return async function snapshot() {
    return {
      sessionId: stream.currentSessionId,
      streamerId: stream.currentStreamerId,
      engineVersion: stream.engineVersion,
      state: stream.state,
      stats: lastStats[lastStats.length - 1] ?? null,
      diagnostics: await stream.getDiagnostics(),
    };
  };
}
```

Call `attachDebug(stream)` directly after `await Streampixel.create(...)`, so that it sees the first events.

**2. Find the phase that failed**

| What you saw | The phase | Go to |
| - | - | - |
| `create()` rejected | Before the stream: the engine download, the project lookup or the ticket. | [Errors from `create()`](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects#errors-from-create) |
| The state never reached `streaming` | Starting: the queue, the app starting, or the video connection. The last `progress` stage tells you how far it got. | Step 3 |
| It streamed, and looked or felt bad | Quality. | Step 4 |
| It streamed, and then stopped | An ending. | Step 3 |

**3. Read how it ended**

The `ended` event names the side to look at.

| Code | Look at |
| - | - |
| `4100` | The viewer's network: it blocks the stream. Send their IT team [Network requirements](https://docs.streampixel.io/resources/concepts/network-requirements.md). |
| `4101` | The path between the viewer and the stream: a firewall or a VPN. Try another network. |
| `4007` | The viewer's connection: it dropped and did not come back within the reconnect window. |
| `4102` | Your app: it stopped sending video. The `stalled` snapshot shows the connection was up. |
| `4003`, `4005`, `4006` | Your app: it reported an error, took too long to start, or closed. |
| `4001` | Capacity: no server was free. See [Capacity](https://docs.streampixel.io/resources/dashboard/capacity.md). |
| `4000`, `4002`, `4004` | The project: switched off, no application found on the server, or the maximum runtime reached. |
| `1008`, `4401` | Access: the ticket was refused. |
| `4103`, `4104` | Not something your page can fix. Contact support if it repeats. |

Every code is explained in [Errors and disconnects](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md#how-a-session-ends). What the SDK tried before it gave up is in [Reliability](https://docs.streampixel.io/resources/web-sdk-v2/reliability.md).

**4. For a quality problem, read the numbers**

Watch `stats` while the problem shows, and use the table in [Reading the numbers](#reading-the-numbers). Check `relayTransport` first: a stream relayed over TCP or TLS has lower quality.

**5. Take a snapshot while the stream is up**

Call the `snapshot()` function that `attachDebug()` returned. After the session ended, `getDiagnostics()` returns `null`, so take it while the problem is visible.

**6. Rule out your own page**

Open the project's share link on the same device and the same network. If the share link shows the same problem, the cause is not in your page.

**7. Compare with the dashboard**

Find the session in your dashboard by its session ID. The session's page shows what the SDK reported. See [Analytics interpretation](https://docs.streampixel.io/resources/dashboard/analytics-interpretation.md).

## What to send to support

Send these to [support@streampixel.io](mailto:support@streampixel.io):

* The session ID and the streamer ID: `stream.currentSessionId` and `stream.currentStreamerId`.
* The engine version: `stream.engineVersion`.
* The `ended` payload: `code`, `reason` and `endKind`. Or, when `create()` rejected, the error's `kind` or `reason` and its `message`.
* The snapshot from `getDiagnostics()`, or the one the `stalled` event carried.
* The time of the problem, with the time zone, and what the viewer saw.

With the session ID, support can read the same session's reports on the platform side.

## Next steps

> [card] [Reliability](https://docs.streampixel.io/resources/web-sdk-v2/reliability.md)
>
> What the SDK does for each failure, and after how many seconds.

> [card] [The engine and updates](https://docs.streampixel.io/resources/web-sdk-v2/engine-and-updates.md)
>
> Where the code in the page comes from, and how it is verified.

> [card] [Events and states](https://docs.streampixel.io/resources/web-sdk-v2/events-and-states.md#streamstats)
>
> Reference: `StreamStats` and every event.

> [card] [Stream API](https://docs.streampixel.io/resources/web-sdk-v2/stream-api.md)
>
> Reference: `getDiagnostics()` and every other method.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.