Resource monitoring
Read CPU, memory, GPU, and VRAM measurements without changing service activity.
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
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
| 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
serviceId: the requested service UUID.intervalSeconds:30.retentionSeconds:21600.state: one of the states above.latest: a detailed current sample, ornull.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
The current source-distributed clients expose the same monitoring API:
oiy metrics SERVICE_ID --minutes 15from 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 before using source-distributed clients. The complete response schema is included in the OpenAPI description.