> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/gym/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/gym/_mcp/server.

# nemo_gym.telemetry.memory

Linux process-tree memory sampling for Gym-managed servers.

## Module Contents

### Classes

| Name                                                                  | Description                                                           |
| --------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [`HostMemory`](#nemo_gym-telemetry-memory-HostMemory)                 | Current host memory capacity and pressure.                            |
| [`MemoryProfiler`](#nemo_gym-telemetry-memory-MemoryProfiler)         | Periodically report host memory and Gym-managed server process trees. |
| [`ProcessTreeMemory`](#nemo_gym-telemetry-memory-ProcessTreeMemory)   | One process tree's current memory.                                    |
| [`ServerMemoryTarget`](#nemo_gym-telemetry-memory-ServerMemoryTarget) | One configured Gym server and the root process Gym spawned for it.    |

### Functions

| Name                                                                                        | Description                                                              |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [`_descendant_pids`](#nemo_gym-telemetry-memory-_descendant_pids)                           | Return a snapshot of a Linux process tree, including its root.           |
| [`_get_instruments`](#nemo_gym-telemetry-memory-_get_instruments)                           | -                                                                        |
| [`_read_process_memory`](#nemo_gym-telemetry-memory-_read_process_memory)                   | Return `(rss, pss)` bytes for one process, or `None` after an exit race. |
| [`collect_host_memory`](#nemo_gym-telemetry-memory-collect_host_memory)                     | Measure current host memory using psutil's cross-platform accounting.    |
| [`collect_process_tree_memory`](#nemo_gym-telemetry-memory-collect_process_tree_memory)     | Measure current RSS and PSS for a root process and its descendants.      |
| [`process_tree_memory_supported`](#nemo_gym-telemetry-memory-process_tree_memory_supported) | Return whether this host exposes Linux procfs memory accounting.         |
| [`record_host_memory`](#nemo_gym-telemetry-memory-record_host_memory)                       | Record current host memory and its sampled peak through Lens.            |
| [`record_server_memory`](#nemo_gym-telemetry-memory-record_server_memory)                   | Record current and sampled-peak process-tree memory through Lens.        |

### Data

[`_INSTRUMENTS`](#nemo_gym-telemetry-memory-_INSTRUMENTS)

[`logger`](#nemo_gym-telemetry-memory-logger)

### API

```python
class nemo_gym.telemetry.memory.HostMemory(
    used_bytes: int,
    available_bytes: int,
    total_bytes: int
)
```

Dataclass

Current host memory capacity and pressure.

**`available_bytes`** `int`

---

**`total_bytes`** `int`

---

**`used_bytes`** `int`

---

```python
class nemo_gym.telemetry.memory.MemoryProfiler(
    targets: list[nemo_gym.telemetry.memory.ServerMemoryTarget],
    interval_seconds: float,
    collector: collections.abc.Callable[[int], nemo_gym.telemetry.memory.ProcessTreeMemory] = collect_process_tree_memory,
    host_collector: collections.abc.Callable[[], nemo_gym.telemetry.memory.HostMemory] = collect_host_memory
)
```

Periodically report host memory and Gym-managed server process trees.

**`_host_peaks`** `dict[str, int] = {}`

---

**`_peaks`** `dict[tuple[str, str], int] = {}`

---

**`_stop`** `= threading.Event()`

---

**`_thread`** `Thread | None = None`

---

```python
nemo_gym.telemetry.memory.MemoryProfiler._run() -> None
```

```python
nemo_gym.telemetry.memory.MemoryProfiler.sample_once() -> None
```

Record one host sample and one sample for every configured server.

```python
nemo_gym.telemetry.memory.MemoryProfiler.start() -> None
```

Start background sampling after recording an initial sample.

```python
nemo_gym.telemetry.memory.MemoryProfiler.stop() -> None
```

Stop sampling and record final live host and process-tree values.

```python
class nemo_gym.telemetry.memory.ProcessTreeMemory(
    rss_bytes: int,
    pss_bytes: int | None,
    process_count: int
)
```

Dataclass

One process tree's current memory.

**`process_count`** `int`

---

**`pss_bytes`** `int | None`

---

**`rss_bytes`** `int`

---

```python
class nemo_gym.telemetry.memory.ServerMemoryTarget(
    name: str,
    server_type: str,
    pid: int
)
```

Dataclass

One configured Gym server and the root process Gym spawned for it.

**`name`** `str`

---

**`pid`** `int`

---

**`server_type`** `str`

---

```python
nemo_gym.telemetry.memory._descendant_pids(
    root_pid: int
) -> set[int]
```

Return a snapshot of a Linux process tree, including its root.

```python
nemo_gym.telemetry.memory._get_instruments(
    meter
) -> dict
```

```python
nemo_gym.telemetry.memory._read_process_memory(
    pid: int
) -> tuple[int, int | None] | None
```

Return `(rss, pss)` bytes for one process, or `None` after an exit race.

```python
nemo_gym.telemetry.memory.collect_host_memory() -> nemo_gym.telemetry.memory.HostMemory
```

Measure current host memory using psutil's cross-platform accounting.

```python
nemo_gym.telemetry.memory.collect_process_tree_memory(
    root_pid: int
) -> nemo_gym.telemetry.memory.ProcessTreeMemory
```

Measure current RSS and PSS for a root process and its descendants.

```python
nemo_gym.telemetry.memory.process_tree_memory_supported() -> bool
```

Return whether this host exposes Linux procfs memory accounting.

```python
nemo_gym.telemetry.memory.record_host_memory(
    memory: nemo_gym.telemetry.memory.HostMemory,
    peaks: dict[str, int]
) -> None
```

Record current host memory and its sampled peak through Lens.

```python
nemo_gym.telemetry.memory.record_server_memory(
    target: nemo_gym.telemetry.memory.ServerMemoryTarget,
    memory: nemo_gym.telemetry.memory.ProcessTreeMemory,
    peaks: dict[tuple[str, str], int]
) -> None
```

Record current and sampled-peak process-tree memory through Lens.

```python
nemo_gym.telemetry.memory._INSTRUMENTS: WeakKeyDictionary = weakref.WeakKeyDictionary()
```

```python
nemo_gym.telemetry.memory.logger = logging.getLogger(__name__)
```