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

# Monitoring a player session

> Observe session state, diagnostics, and the event plane to operate a game confidently.

Once a player is connected you should be able to answer three questions at any
time: *Is the session valid? What is the SDK doing? Are events flowing?*

## 1. Session state

Use the SDK-stated status machine rather than guessing from gameplay:

```ts theme={"dark"}
const status = box.getStatus();                 // { state: "authenticated", ... }
const sessionStatus = box.getSessionStatus();   // finer-grained session state
const context = box.getPlayerContext();          // tournamentId, matchId, participantId, slot
```

Signal to the player:

* session not yet open, pending validation, active, or expired,
* a match context that no longer matches the current UI.

## 2. Diagnostics

```bash theme={"dark"}
musterbox diagnostics health          # one-shot checks
musterbox diagnostics health --watch  # continuous
musterbox diagnostics generate        # support bundle during incidents
musterbox pipeline status             # outbound queue pressure
musterbox transport diagnose          # control-plane connectivity
musterbox web-socket diagnose         # event-plane connectivity
```

## 3. The event plane

Inbound session/wallet/status events are dispatched to your handlers:

```ts theme={"dark"}
box.addEventListener("event", (evt) => {
  switch (evt.data.type) {
    case "session": renderSession(evt.data); break;
    case "status":  renderStatus(evt.data);  break;
    case "wallet":  refreshWallet(evt.data); break;
  }
});
```

In `Manual` runtime mode, remember to call `tick` each frame — that is what
dispatches events and polls the plane.

## 4. Recognizing anomalies

| Symptom                                 | Likely cause               | Action                                          |
| --------------------------------------- | -------------------------- | ----------------------------------------------- |
| `MBX-SDK-008` repeated                  | Refresh failing repeatedly | Re-authenticate the player                      |
| `MBX-SDK-011`                           | Outbound queue full        | Reduce submit rate; check connectivity          |
| `pending` forever on results            | Opponent has not claimed   | Wait; show "awaiting opponent"                  |
| Transport errors against production URL | Environment misconfigured  | Check `baseUrl`/environment                     |
| `NotAuthenticated` mid-game             | Session expired            | Re-authenticate, never continue unauthenticated |

## Instrumentation summary

* Log **sdk version + ABI** in your diagnostics footer (1.0.0 / 1.2.0).
* Capture a **diagnostic bundle** before filing anything.
* Never log tokens, PINs, or the game key. SDK output is pre-redacted; your
  own logs should be too.

Next: [Events & realtime](/guides/events-and-realtime).