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

# Monitor Stream

> Subscribe to live snapshot, update, metrics, process, and error events.

## Subscribe

The monitor stream is a WebSocket channel (`/v1/monitor/ws`). The Python SDK and
CLI manage the connection; raw HTTP clients perform the upgrade and send a
`monitor_subscribe` message as described in the
[WebSocket protocol](../reference/websocket-protocol). The TypeScript SDK does
not expose a monitor stream.

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  from nullspace import Monitor

  monitor = Monitor()
  subscription = monitor.subscribe(
      interval_ms=1_000,
      include_processes=True,
      on_metrics=lambda event: print(event.metrics),
      on_processes=lambda event: print(event.processes),
      on_error=lambda event: print(event.message),
  )

  # Keep your application alive while the background reader receives events.
  subscription.stop()
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace monitor stream --interval-ms 1000 --include-processes
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # WebSocket upgrade; send a `monitor_subscribe` message after connecting.
  # See ../reference/websocket-protocol for message shapes.
  wscat -c "${NULLSPACE_API_URL}/v1/monitor/ws" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

The monitor WebSocket accepts a `monitor_subscribe` message with an optional
`interval_ms` and `include_processes` flag. Server-side intervals are clamped
to the supported range: 500 ms to 10,000 ms.

## Metrics endpoint

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  metrics = machine.get_metrics()
  for sample in metrics:
      print(sample)
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  const metrics = await machine.getMetrics();
  for (const sample of metrics) {
    console.log(sample);
  }
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine metrics mch_123 --json
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl "${NULLSPACE_API_URL}/v1/machines/mch_123/metrics" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

## Event classes

Monitor streams can emit snapshot, update, metrics, processes, and error
events. Use callback parameters for only the event types your application needs.

| Callback       | Message type                                        |
| -------------- | --------------------------------------------------- |
| `on_snapshot`  | Initial snapshot of observed machine state.         |
| `on_update`    | State update after the snapshot.                    |
| `on_metrics`   | CPU, memory, and runtime metrics.                   |
| `on_processes` | Process list updates when `include_processes=True`. |
| `on_error`     | Subscription or stream errors.                      |

## Related

* [Metrics and timeouts](../machines/metrics-timeouts)
* [WebSockets](../networking/websockets)
* [WebSocket protocol](../reference/websocket-protocol)