Skip to main content

Retrieve Virtual Machine Performance Metrics

GET https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/{id}/metrics​

Retrieves performance metrics data for a virtual machine. Provide the virtual machine ID in the path to retrieve the following data for the specified virtual machine: CPU usage, memory usage (RAM), network.in, network.out, disk.read, and disk.write. The optional duration parameter can be used to specify the period for retrieving performance metrics; the default value will retrieve all available data.


Path parameters​

id integer   Required​

The id of the virtual machine from which to retrieve performance metrics.


Query string parameters​

duration enum  optional​

Specifies the time period for retrieving performance metrics. If no duration is specified, all recorded performance metrics are returned.

Possible enum values: 1h, 2h, 4h, 6h, 12h, 1d, 3d, 7d, 15d, 30d


Attributes​

cpu object​

An object containing CPU performance metrics.

Show child attributes
unit string​

The unit of measurement for CPU metrics (e.g., "nanoseconds").

columns array​

An array containing the column names for CPU metrics. Includes time for the timestamp of the event, granularity for the frequency at which values are sampled, and the performance value in nanoseconds.

data array​

An array containing data points for CPU metrics.

Show child attributes
time string​

The timestamp when the metric data was recorded.

granularity string​

The frequency at which CPU usage values are sampled (e.g., 300 seconds, which is every 5 minutes).

value integer​

The value of the CPU metric in nanoseconds.

memory.usages object​

An object containing memory usage metrics.

Show child attributes
unit string​

The unit of measurement for memory usage metrics (e.g., "megabytes").

columns array​

An array containing the column names for memory usage metrics. Includes time for the timestamp of the event, granularity for the frequency at which values are sampled, and the performance value in megabytes.

data array​

An array containing data points for memory usage metrics.

Show child attributes
time string​

The timestamp when the metric data was recorded.

**granularity** string`​

The frequency at which memory usage values are sampled (e.g., 300 seconds, which is every 5 minutes).

value number​

The value of memory usage metric in MB.

network.in object​

An object containing network input metrics.

Show child attributes
unit string​

The unit of measurement for network input metrics (e.g., "bytes").

columns array​

An array containing the column names for network input metrics. Includes time for the timestamp of the event, granularity for the frequency at which values are sampled, and the performance value in bytes.

data array​

An array containing data points for network input metrics.

Show child attributes
time string​

The timestamp when the metric data was recorded.

granularity string​

The frequency at which network input values are sampled (e.g., 300 seconds, which is every 5 minutes).

value integer​

The value of network input metric in bytes.

network.out object​

An object containing network output metrics.

Show child attributes
unit string​

The unit of measurement for network output metrics (e.g., "bytes").

columns array​

An array containing the column names for network output metrics. Includes time for the timestamp of the event, granularity for the frequency at which values are sampled, and the performance value in bytes.

data array​

An array containing data points for network output metrics.

Show child attributes
time string​

The timestamp when the metric data was recorded.

granularity string​

The frequency at which network output values are sampled (e.g., 300 seconds, which is every 5 minutes).

value integer​

The value of network output metric in bytes.

disk.read object​

An object containing disk read metrics.

Show child attributes
unit string​

The unit of measurement for disk read metrics (e.g., "bytes").

columns array​

An array containing the column names for disk read metrics. Includes time for the timestamp of the event, granularity for the frequency at which values are sampled, and the performance value in bytes.

data array​

An array containing data points for disk read metrics.

Show child attributes
time string​

The timestamp when the metric data was recorded.

granularity string​

The frequency at which disk read values are sampled (e.g., 300 seconds, which is every 5 minutes).

value integer​

The value of disk read metric in bytes.

disk.write object​

An object containing disk write metrics.

Show child attributes
unit string​

The unit of measurement for disk write metrics (e.g., "bytes").

columns array​

An array containing the column names for disk write metrics. Includes time for the timestamp of the event, granularity for the frequency at which values are sampled, and the performance value in bytes.

data array​

An array containing data points for disk write metrics.

Show child attributes
time string​

The timestamp when the metric data was recorded.

granularity string​

The frequency at which disk write values are sampled (e.g., 300 seconds, which is every 5 minutes).

value integer​

The value of disk write metric in bytes.


note

Only the first event for each of the virtual machine resources is shown in this example. Calling the GET /core/virtual-machines/{virtual_machine_id}/metrics endpoint will return all events for the following resources: cpu usage, memory.usage (RAM), network.in, network.out, disk.read, and disk.write.

Example request
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/{id}/metrics" \
 -H "accept: application/json"\
 -H "api_key: YOUR API KEY"
Response
{
    "cpu": {
        "unit": "ns",
        "columns": [
            "time",
            "granularity",
            "value"
        ],
        "data": [
          [
            "2023-05-17T12:45:00+00:00",
            300,
            760872710000000
          ],
          [...]
        ],

    },
    "memory.usages": {
        "unit": "MB",
        "columns": [
            "time",
            "granularity",
            "value"
        ],
        "data": [
          [
            "2023-05-17T12:45:00+00:00",
            300,
            937.
          ],
          [...]
        ]
    },
    "network.in": {
        "unit": "B",
        "columns": [
            "time",
            "granularity",
            "value"
        ],
        "data": [
          [
            "2023-05-17T12:45:00+00:00",
            300,
            821185824
          ],
          [...]
        ]
    },
    "network.out": {
        "unit": "B",
        "columns": [
            "time",
            "granularity",
            "value"
        ],
        "data": [
          [
            "2023-05-17T12:45:00+00:00",
            300,
            3440028467
          ],
          [...]
        ]
    },
    "disk.read": {
        "unit": "B",
        "columns": [
            "time",
            "granularity",
            "value"
        ],
        "data": [
          [
            "2023-05-17T12:45:00+00:00",
            300,
            2534269952
          ],
          [...]
        ]
    },
    "disk.write": {
        "unit": "B",
        "columns": [
            "time",
            "granularity",
            "value"
        ],
        "data": [
          [
            "2023-05-17T12:45:00+00:00",
            300,
            397276770304
          ],
          [...]
        ]
    }
}


Returns​

The data array containing events recorded for each resource (CPU usage, memory usage (RAM), network.in, network.out, disk.read, and disk.write) is returned. The data returned includes; the date and time, the granularity (frequency at which the resource performance values are sampled, which in this case is 300 seconds or 5 minutes.), and the performance value in units corresponding to the resource type.



Back to top​