# Resource monitoring

Source: https://docs.oiy.ai/docs/services/monitoring

Read CPU, memory, GPU, and VRAM measurements without changing service activity.



<div className="preview-banner">
  <strong>DEPLOYMENT-DEPENDENT CAPABILITY</strong>

  Monitoring is implemented in the current preview source. Live readings require the updated control plane and configured regional collectors. A valid resource profile or running service does not, by itself, prove that every metric source is available.
</div>

## What is measured [#what-is-measured]

| Metric | Meaning                                                                                         |
| ------ | ----------------------------------------------------------------------------------------------- |
| CPU    | Workload CPU utilization relative to its allocation where the runtime provides that measurement |
| Memory | Workload system-memory utilization                                                              |
| GPU    | Mean utilization of the assigned GPU devices                                                    |
| VRAM   | Used framebuffer memory divided by assigned framebuffer capacity                                |

CPU and system RAM are distinct from GPU utilization and VRAM. Per-device data is included when available. Physical GPU identifiers, host addresses, and supplier credentials are not returned.

A measured `0` means zero usage. `null` means a reading is missing or unsupported. Do not plot missing values as zero.

## Read the API [#read-the-api]

```sh
curl "$OIY_API_URL/api/services/$SERVICE_ID/metrics?minutes=60" \
  -H "Authorization: Bearer $OIY_API_KEY"
```

The supported windows are `15`, `60`, and `360` minutes; the default is `60`. Collection runs approximately every 30 seconds, and history is retained for six hours. Responses are not cached.

Reading metrics does not wake a sleeping service, protect a task, or reset its idle timer. Monitoring is diagnostic and does not meter billing.

## Interpret the response state [#interpret-the-response-state]

| State         | Interpretation                                                                       |
| ------------- | ------------------------------------------------------------------------------------ |
| `live`        | The current revision has a fresh sample with its expected metrics present.           |
| `partial`     | A fresh sample exists, but one or more expected values are unavailable.              |
| `stale`       | The latest sample for the current revision is older than 90 seconds.                 |
| `unavailable` | There is no usable current sample.                                                   |
| `inactive`    | Compute is not allocated or the service is sleeping, stopping, deleting, or deleted. |

Paused services can retain historical samples, but `latest` is `null` while inactive. History may contain earlier revisions or allocation generations. Break chart lines across changes in `revision` or `generation`, missing readings, and long collection gaps.

## Response fields [#response-fields]

* `serviceId`: the requested service UUID.
* `intervalSeconds`: `30`.
* `retentionSeconds`: `21600`.
* `state`: one of the states above.
* `latest`: a detailed current sample, or `null`.
* `samples`: compact historical points with timestamp, revision, allocation generation, and the four percentage values.

Detailed samples include nullable absolute core/byte counts, assigned-device readings, and `unavailable` reasons for CPU, memory, GPU, and VRAM. Source limitations can prevent an absolute count even when a percentage is available. `observedAt` is a Unix timestamp in milliseconds; the opaque `generation` value identifies a measurement continuity boundary, not a physical device.

## CLI, Python, and MCP [#cli-python-and-mcp]

The current source-distributed clients expose the same monitoring API:

```sh
oiy metrics SERVICE_ID --minutes 15
```

```python
from oiy_ai import Client

history = Client().metrics("SERVICE_ID", minutes=15)
```

MCP `oiy_metrics` returns current status and summary statistics. History is opt-in and capped at 120 recent points. Averages and peaks describe observed samples, not an estimate for missing periods.

See [developer installation](/docs/developers) before using source-distributed clients. The complete response schema is included in the [OpenAPI description](/openapi.json).