Virtual machine (VM) instance insights help you understand the CPU, memory, and network usage of your Compute Engine VMs. Insights are generated automatically based on system metrics or metrics gathered by Cloud Monitoring. You can use insights to support decisions about resizing your machine types to more efficiently use VM resources.
For more information about insights, see Insights.
Select the tab for how you plan to use the samples on this page:
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:
gcloud initIf you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
Compute Engine generates recommendations based on resource insights. Recommendations include machine type recommendations and idle VM recommendations.
By viewing insights associated with a specific VM, you can learn more about the CPU, memory, and network usage for your VM.
To view the insights that generated a specific recommendation, use the gcloud CLI or the API.
To perform this task, you must have the following permissions:
recommender.computeInstanceCpuUsageInsights.get on the projectrecommender.computeInstanceCpuUsageInsights.list on the projectrecommender.computeInstanceCpuUsagePredictionInsights.get on the projectrecommender.computeInstanceCpuUsagePredictionInsights.list on the projectrecommender.computeInstanceCpuUsageTrendInsights.get on the projectrecommender.computeInstanceCpuUsageTrendInsights.list on the projectrecommender.computeInstanceMemoryUsageInsights.get on the projectrecommender.computeInstanceMemoryUsageInsights.list on the projectrecommender.computeInstanceMemoryUsagePredictionInsights.get on the projectrecommender.computeInstanceMemoryUsagePredictionInsights.list on the projectrecommender.computeInstanceNetworkThroughputInsights.get on the projectrecommender.computeInstanceNetworkThroughputInsights.list on the projectTo view all the available insights in detail for a specific zone, use the
insights list command
and provide the --format option.
gcloud recommender insights list --project=PROJECT_ID \ --location=LOCATION \ --insight-type=INSIGHT_TYPE_ID \ --format=FORMAT
Replace the following:
PROJECT_ID: the ID of your project.LOCATION: the zone that contains the resources
for which you want to view insights.INSIGHT_TYPE_ID: the id of the
insight type. For a list of
the VM insights available, see
Types of VM instance insights.FORMAT: your preferred output
format–for example, json.A typical output of the insights list command using the json output
format might look like the following.
[
{
"associatedRecommendations": [
{
"recommendation": "projects/PROJECT_ID/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/7618763b-fee2-42e5-8b9b-e6eee0b2077f"
}
],
"category": "PERFORMANCE",
"content": {
"predictedCpuCores": 0.15
},
"description": "Predicted CPU usage is 0.1 vCPUs.",
"etag": "\"fdb51460cac758a0\"",
"insightSubtype": "CPU_USAGE_PREDICTION",
"lastRefreshTime": "2021-09-15T06:50:45Z",
"name": "projects/PROJECT_ID/locations/us-central1-a/insightTypes/google.compute.instance.CpuUsagePredictionInsight/insights/cb2ab4e6-2c5e-4f0e-8cbe-1487e8bae8c0",
"observationPeriod": "604800s",
"severity": "LOW",
"stateInfo": {
"state": "ACTIVE"
},
"targetResources": [
"//compute.googleapis.com/projects/PROJECT_ID/zones/us-central1-a/instances/instance-name-1"
]
}
]
To view all the available insights in detail for a specific zone, use the
insights.list method.
GET https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/insightTypes/INSIGHT_TYPE_ID/insights
Replace the following:
PROJECT_ID: the ID of your project.LOCATION: the zone that contains the
resources for which you want to view insights.INSIGHT_TYPE_ID: the id of the
insight Type. For a list of
the VM insights available, see
Types of VM instance insights.A typical output of the insights.list method might look like
the following.
[
{
"associatedRecommendations": [
{
"recommendation": "projects/PROJECT_ID/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/7618763b-fee2-42e5-8b9b-e6eee0b2077f"
}
],
"category": "PERFORMANCE",
"content": {
"predictedCpuCores": 0.15
},
"description": "Predicted CPU usage is 0.1 vCPUs.",
"etag": "\"fdb51460cac758a0\"",
"insightSubtype": "CPU_USAGE_PREDICTION",
"lastRefreshTime": "2021-09-15T06:50:45Z",
"name": "projects/PROJECT_ID/locations/us-central1-a/insightTypes/google.compute.instance.CpuUsagePredictionInsight/insights/cb2ab4e6-2c5e-4f0e-8cbe-1487e8bae8c0",
"observationPeriod": "604800s",
"severity": "LOW",
"stateInfo": {
"state": "ACTIVE"
},
"targetResources": [
"//compute.googleapis.com/projects/PROJECT_ID/zones/us-central1-a/instances/instance-name-1"
]
}
]
For more information about insights, see the reference docs.
You can use different insights to retrieve information about the performance of your VMs. Each insight type has specific content attributes.
The following sections provide a reference for the VM insights available.
Compute Engine creates CPU usage insights when the CPU usage of your VMs has been higher or lower than usual for the last observation period.
The insight type ID is google.compute.instance.CpuUsageInsight.
The available subtypes are:
HIGH_CPU_USAGELOW_CPU_USAGEThese are associated with insight descriptions such as the following:
In the last 12 days for 90% of the time, CPU usage was greater
than or equal to 83%.In the last 10 days for 70% of the time, CPU usage was lower than
or equal to 20%.The following table provides some details about the content associated with CPU usage insights.
| Attribute | Type | Description |
points
|
ARRAY | Array of objects. Each object contains the following properties:
|
Compute Engine creates CPU usage prediction insights to indicate the predicted CPU usage for the following day.
The insight type ID is google.compute.instance.CpuUsagePredictionInsight.
A typical description you can find in this insight is similar to the following:
Predicted CPU usage is 0.1 vCPUs.The following table provides some details about the content associated with CPU usage prediction insights.
| Attribute | Type | Description |
predicted_cpu_cores
|
DOUBLE | Predicted amount of CPU cores. |
Compute Engine creates CPU usage trend insights when CPU usage shows an increasing or decreasing trend in the last observation period.
The insight type ID is google.compute.instance.CpuUsageTrendInsight.
The available subtypes are:
CPU_USAGE_INCREASECPU_USAGE_DECREASEThese are generally associated with insight descriptions such as the following:
In the last 7 days, average daily CPU usage has increased by 8%
from 65% to 73%.In the last 7 days, average daily CPU usage has decreased by 10%
from 55% to 45%.The following table provides some details about the content associated with CPU usage trend insights.
cpu_usage_percentage_at_start
cpu_usage_percentage_at_end
cpu_usage_percentage_change
Prediction uses linear regression to model the change of daily CPU usage.
The value represents the percentage of the total number of vCPUs, and is in the range [0, 100].
Compute Engine creates memory usage insights if the memory usage is exceptionally high or low during the observation period.
The insight type ID is google.compute.instance.MemoryUsageInsight.
The available subtypes are:
HIGH_MEMORY_USAGELOW_MEMORY_USAGEThese are generally associated with insight descriptions such as the following:
In the last 12 days for 80% of the time, memory usage was greater
than or equal to 64%.In the last 7 days for 50% of the time, memory usage was lower than
or equal to 10%.The following table provides some details about the content associated with memory usage insights.
| Attribute | Type | Description |
points
|
ARRAY |
Array of objects. Each object contains the following properties:
|
Compute Engine creates memory usage prediction insights to indicate the memory usage predicted for the following day.
The insight type ID is google.compute.instance.MemoryUsagePredictionInsight.
A typical insight description is the following:
Predicted memory usage is 1536 MB.The following table provides some details about the content associated with memory usage prediction insights.
| Attribute | Type | Description |
predicted_memory_mb
|
DOUBLE | Predicted amount of memory expressed in MB. |
Compute Engine creates network throughput insights when the network throughput during the observation period is exceptionally low for the incoming or outgoing traffic.
The insight type ID is google.compute.instance.NetworkThroughputInsight.
The available subtypes are:
LOW_RECEIVED_NETWORK_THROUGHPUTLOW_SENT_NETWORK_THROGHPUTThese are generally associated with insight descriptions such as the following:
In the last 7 days for 80% of the time, received network throughput was
lower than or equal to 500 B/s.In the last 7 days for 80% of the time, sent network throughput was
lower than or equal to 200 B/s.The following table provides some details about the content associated with network throughput insights.
sample_probability
The value is in the range [0, 1].
quantile_function_value_in_bytes_per_second
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-06-09 UTC.