> ## 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.

# Observability

> Monitor machine lifecycle events, webhooks, and runtime metrics.

Observability helps you answer what happened to a machine, whether long-running
work is still healthy, and which events your application should react to.

Use lifecycle events for durable state transitions, webhooks for application
notifications, and monitor streams for live metrics and process snapshots.

## Choose A Signal

| Need                                                                           | Use                                                  |
| ------------------------------------------------------------------------------ | ---------------------------------------------------- |
| List or stream create, pause, resume, hibernate, fork, and destroy transitions | [Lifecycle events](./lifecycle-events)               |
| Notify your service when lifecycle events happen                               | [Webhooks](./webhooks)                               |
| Watch live CPU, memory, process, update, and error events                      | [Monitor machines](./monitor)                        |
| Inspect timeout behavior and resource usage                                    | [Metrics and timeouts](../machines/metrics-timeouts) |

## Quick Examples

List recent lifecycle events:

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
from nullspace import Lifecycle

lifecycle = Lifecycle()
events = lifecycle.list_events(limit=20)
for event in events.events:
    print(event.operation, event.status, event.machine_id)
lifecycle.close()
```

Subscribe to live monitor metrics:

```python 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),
)
subscription.stop()
```

## Operational Guidance

| Situation                             | Guidance                                                                 |
| ------------------------------------- | ------------------------------------------------------------------------ |
| A workflow owns a specific machine    | Use per-machine lifecycle and metrics helpers.                           |
| A control plane watches many machines | Use lifecycle list/stream filters and webhooks.                          |
| A process may be alive but not ready  | Combine monitor data with command, process, or preview readiness checks. |
| You need retryable automation         | Persist event IDs and resume streams with `after_event_id`.              |

## Observability Guides

<CardGroup cols={2}>
  <Card title="Lifecycle events" href="./lifecycle-events">
    Understand state changes such as create, pause, resume, hibernate, and stop.
  </Card>

  <Card title="Webhooks" href="./webhooks">
    Receive event notifications in your own service.
  </Card>

  <Card title="Monitor machines" href="./monitor">
    Inspect resource usage and operational state.
  </Card>
</CardGroup>

## Related

* [Machine metrics and timeouts](../machines/metrics-timeouts)
* [Lifecycle](../machines/lifecycle)
* [WebSockets](../networking/websockets)