Skip to main content

Performance Metrics and Events History

The Infrahub API provides powerful tools for accessing comprehensive performance data and detailed event history related to your virtual machines.

In this article


Performance Metrics

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

The performance metrics resource can be used to retrieve data relating to the performance of a specified virtual machine. The performance metrics endpoint retrieves the following data from a designated virtual machine: CPU usage, memory usage (RAM), network.in, network.out, disk.read, and disk.write.

In the following example, the performance metrics are retrieved for a virtual machine with an ID of "5" as specified in the path of the request. No duration is included as a query string parameter, so all performance metrics data are retrieved.


Path parameters


virtual_machine_id REQUIRED integer

The id of the virtual machine from which to retrieve performance metrics.
In this example, an ID value of "5" is specified in the path of the request.


Query string parameters


duration optional enum

The period of time over which to retrieve performance metrics. If no duration is specified, all recorded performance metrics are returned.
In this example, no duration is specified, so all data are returned.

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


Returns


The data array containing events recorded for each resource is returned. The data returned includes; the date and time, the granularity (frequency at which the resource performance values are sampled), and the performance value in units corresponding to the resource type.

In this example the following data for the CPU resource are returned for a virtual machine with an ID of "5" as specified in the path of the request: the date/time is "2023-05-17T12:45:00+00:00", the granularity is "300" seconds (or 5 minutes), and the performance value is "760872710000000" nanoseconds or 8.8 days.


Attributes of the Performance Metrics object


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/5/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
],
[...]
]
}
}



Events History

GET https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/{virtual_machine_id}/events

The details of all actions performed on a virtual machine are captured as events. A comprehensive history of a virtual machine's events can be accessed by using the events history endpoint.

In the following example, a complete history of events is returned for the virtual machine with an ID of "62" as specified in the path of the request.


Path parameters


virtual_machine_id REQUIRED integer

The id of the virtual machine from which to retrieve a history of events.


Returns


The following information is returned: the status field, which can be either "true" (indicating success) or "false" (indicating failure), and a message field is provided to further clarify the status. The response also returns an array of virtual_machine_events objects, each of which provides comprehensive details about individual virtual machine events.


Attributes of the Virtual Machine Events object


status boolean

Indicates the status of the request, "true" (indicating success) or "false" (indicating failure).


message string

A message providing information about the status of the request.


virtual_machine_events array

An array containing objects representing virtual machine events.

Show event attributes
time date-time

The timestamp when the event occurred.


type string

The type of the event (e.g., "normal").


user_id integer

The ID of the user associated with the event.


message string

A message describing the operation executed on the virtual machine.


virtual_machine_id integer

The ID of the virtual machine related to the event.


reason string

The operation name of the event (e.g., "VirtualMachineCreationRequest", which specifies a request to create a virtual machine).


object string

The object associated with the event (e.g., "vm 2").


org_id integer

The ID of the organization associated with the event.

Example request
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/62/events" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"
Response
{
"status": true,
"message": "Getting virtual machine events success",
"virtual_machine_events": [
{
"time": "2023-06-14T08:10:57",
"type": "normal",
"user_id": 10,
"message": "Virtual machine vm 2 Creation Request Sent.",
"virtual_machine_id": 62,
"reason": "VirtualMachineCreationRequest",
"object": "vm 2",
"org_id": 10
},
{...}

Back to top