> This page is for version 0.6.0.
> For other versions, use one of these documentation indexes:
> - Main (default): https://docs.nvidia.com/nemo/gym/main/llms.txt
> - 0.7.0: https://docs.nvidia.com/nemo/gym/v0.7.0/llms.txt
> - 0.6.0: https://docs.nvidia.com/nemo/gym/v0.6.0/llms.txt
> - 0.5.1: https://docs.nvidia.com/nemo/gym/v0.5.1/llms.txt
> - 0.5.0: https://docs.nvidia.com/nemo/gym/v0.5.0/llms.txt
> - 0.4.0: https://docs.nvidia.com/nemo/gym/v0.4.0/llms.txt
> - 0.3.0: https://docs.nvidia.com/nemo/gym/v0.3.0/llms.txt
> - 0.2.1: https://docs.nvidia.com/nemo/gym/v0.2.1/llms.txt

> 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.sandbox.resource_telemetry

Best-effort resource records in the existing sandbox trace stream.

## Module Contents

### Classes

| Name                                                                              | Description                                                                        |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [`ComponentAllocation`](#nemo_gym-sandbox-resource_telemetry-ComponentAllocation) | Observed reservations and limits for one explicitly named component.               |
| [`ResourceAllocation`](#nemo_gym-sandbox-resource_telemetry-ResourceAllocation)   | Provider-independent allocation record; placement is optional.                     |
| [`ResourceDesignator`](#nemo_gym-sandbox-resource_telemetry-ResourceDesignator)   | Opaque infrastructure identity interpreted by kind, within an optional scope.      |
| [`ResourceProvider`](#nemo_gym-sandbox-resource_telemetry-ResourceProvider)       | Optional read-only capability; values carry explicit provider/source semantics.    |
| [`ResourceSampler`](#nemo_gym-sandbox-resource_telemetry-ResourceSampler)         | One owner samples a sandbox; borrowed connections do not start duplicate samplers. |

### Functions

| Name                                                                                  | Description                                                                         |
| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [`allocation_attributes`](#nemo_gym-sandbox-resource_telemetry-allocation_attributes) | Use identical OTEL keys for every provider's typed allocation.                      |
| [`amount_attributes`](#nemo_gym-sandbox-resource_telemetry-amount_attributes)         | Serialize shared resource quantities without losing unspecified values.             |
| [`record_request`](#nemo_gym-sandbox-resource_telemetry-record_request)               | Give one logical sandbox request an identity, even if provisioning never succeeds.  |
| [`requested_attributes`](#nemo_gym-sandbox-resource_telemetry-requested_attributes)   | Declared shape only. Absent values are unknown, never zero or effective allocation. |
| [`sampling_interval`](#nemo_gym-sandbox-resource_telemetry-sampling_interval)         | Return zero unless resource traces are enabled, including an actual exporter.       |

### Data

[`Attribute`](#nemo_gym-sandbox-resource_telemetry-Attribute)

[`LOGGER`](#nemo_gym-sandbox-resource_telemetry-LOGGER)

[`PREFIX`](#nemo_gym-sandbox-resource_telemetry-PREFIX)

### API

```python
class nemo_gym.sandbox.resource_telemetry.ComponentAllocation(
    name: str,
    requests: nemo_gym.sandbox.providers.base.SandboxResourceAmounts = SandboxResourceAmounts(),
    limits: nemo_gym.sandbox.providers.base.SandboxResourceAmounts = SandboxResourceAmounts()
)
```

Dataclass

Observed reservations and limits for one explicitly named component.

**`limits`** `SandboxResourceAmounts = field(default_factory=SandboxResourceAmounts)`

---

**`name`** `str`

---

**`requests`** `SandboxResourceAmounts = field(default_factory=SandboxResourceAmounts)`

---

```python
class nemo_gym.sandbox.resource_telemetry.ResourceAllocation(
    source: str,
    components: tuple[nemo_gym.sandbox.resource_telemetry.ComponentAllocation, ...] = (),
    designator: nemo_gym.sandbox.resource_telemetry.ResourceDesignator | None = None,
    host: nemo_gym.sandbox.resource_telemetry.ResourceDesignator | None = None
)
```

Dataclass

Provider-independent allocation record; placement is optional.

**`components`** `tuple[ComponentAllocation, ...] = ()`

---

**`designator`** `ResourceDesignator | None = None`

---

**`host`** `ResourceDesignator | None = None`

---

**`source`** `str`

---

```python
class nemo_gym.sandbox.resource_telemetry.ResourceDesignator(
    kind: str,
    id: str,
    scope: str | None = None
)
```

Dataclass

Opaque infrastructure identity interpreted by kind, within an optional scope.

This is not a network endpoint or reconnect descriptor and contains no credentials.
Scope identifies the deployment/cluster/daemon in which the ID is meaningful.

**`id`** `str`

---

**`kind`** `str`

---

**`scope`** `str | None = None`

---

```python
class nemo_gym.sandbox.resource_telemetry.ResourceProvider()
```

Protocol

Optional read-only capability; values carry explicit provider/source semantics.

```python
nemo_gym.sandbox.resource_telemetry.ResourceProvider.resource_allocation(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle
) -> nemo_gym.sandbox.resource_telemetry.ResourceAllocation
```

async

```python
nemo_gym.sandbox.resource_telemetry.ResourceProvider.resource_sample(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle
) -> dict[str, nemo_gym.sandbox.resource_telemetry.Attribute]
```

async

```python
class nemo_gym.sandbox.resource_telemetry.ResourceSampler(
    provider: nemo_gym.sandbox.resource_telemetry.ResourceProvider,
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    attributes: collections.abc.Mapping[str, nemo_gym.sandbox.resource_telemetry.Attribute],
    interval: float
)
```

One owner samples a sandbox; borrowed connections do not start duplicate samplers.

**`attributes`** `= dict(attributes)`

---

**`task`** `Task[None] | None = None`

---

```python
nemo_gym.sandbox.resource_telemetry.ResourceSampler.record(
    kind: str,
    final: bool = False
) -> None
```

async

```python
nemo_gym.sandbox.resource_telemetry.ResourceSampler.run() -> None
```

async

```python
nemo_gym.sandbox.resource_telemetry.ResourceSampler.start() -> None
```

```python
nemo_gym.sandbox.resource_telemetry.ResourceSampler.stop() -> None
```

async

```python
nemo_gym.sandbox.resource_telemetry.allocation_attributes(
    allocation: nemo_gym.sandbox.resource_telemetry.ResourceAllocation
) -> dict[str, nemo_gym.sandbox.resource_telemetry.Attribute]
```

Use identical OTEL keys for every provider's typed allocation.

```python
nemo_gym.sandbox.resource_telemetry.amount_attributes(
    amounts: nemo_gym.sandbox.providers.base.SandboxResourceAmounts,
    prefix: str
) -> dict[str, nemo_gym.sandbox.resource_telemetry.Attribute]
```

Serialize shared resource quantities without losing unspecified values.

```python
nemo_gym.sandbox.resource_telemetry.record_request(
    spec: nemo_gym.sandbox.providers.base.SandboxSpec,
    attributes: collections.abc.Mapping[str, nemo_gym.sandbox.resource_telemetry.Attribute]
) -> dict[str, nemo_gym.sandbox.resource_telemetry.Attribute]
```

Give one logical sandbox request an identity, even if provisioning never succeeds.

```python
nemo_gym.sandbox.resource_telemetry.requested_attributes(
    spec: nemo_gym.sandbox.providers.base.SandboxSpec
) -> dict[str, nemo_gym.sandbox.resource_telemetry.Attribute]
```

Declared shape only. Absent values are unknown, never zero or effective allocation.

```python
nemo_gym.sandbox.resource_telemetry.sampling_interval() -> float
```

Return zero unless resource traces are enabled, including an actual exporter.

```python
nemo_gym.sandbox.resource_telemetry.Attribute = str | int | float | bool
```

```python
nemo_gym.sandbox.resource_telemetry.LOGGER = logging.getLogger(__name__)
```

```python
nemo_gym.sandbox.resource_telemetry.PREFIX = 'nemo.gym.sandbox.'
```