This document explains how to monitor the consumption of reservations of Compute Engine zonal resources by using Cloud Monitoring.
Monitoring collects and stores performance information of Google Cloud services such as Compute Engine. The performance information is called metrics and time series. You can access the metrics and time series of your Compute Engine reservations to do the following:
Display how your reservations are being consumed by using Monitoring dashboards.
Receive timely notifications when the consumption of your reservations is in a specific state by using Monitoring alerting policies.
These methods can, for example, help you verify that your reservations are being consumed as you planned or timely act to avoid unnecessary costs from wasted resources or unused reservations.
Before you begin
- Review the requirements and restrictions for reservations.
-
Enable the Monitoring API.
-
If you haven't already, then set up authentication.
Authentication is
the process by which your identity is verified for access to Google Cloud services and APIs.
To run code or samples from a local development environment, you can authenticate to
Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
REST
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, then initialize it by running the following command:
gcloud init
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
Required roles
To get the permissions that you need to create Monitoring dashboards or alerting
policies to monitor the consumption of reservations,
ask your administrator to grant you the
Monitoring Admin (roles/monitoring.admin
) IAM role on the project.
For more information about granting roles, see Manage access to projects, folders, and organizations.
This predefined role contains the permissions required to create Monitoring dashboards or alerting policies to monitor the consumption of reservations. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to create Monitoring dashboards or alerting policies to monitor the consumption of reservations:
-
To create dashboards:
monitoring.dashboards.create
on the project -
To create policy alerts:
monitoring.alertPolicies.create
on the project
You might also be able to get these permissions with custom roles or other predefined roles.
Restrictions
When using Monitoring to access and view the time series of a reservation, the following restrictions apply:
After you create a reservation, its time series becomes available within 30 minutes.
After a time series becomes available, Monitoring starts updating it at least once every 30 minutes.
If you delete a reservation, its time series is also deleted and can't be recovered.
You can only access and view the time series of a reservation that was created in the current project.
For more information about Monitoring restrictions, see Cloud Monitoring quotas and limits.
Reservations metrics
When creating Monitoring dashboards or alerting policies, you must first select the Google Cloud metric to measure how the Google Cloud service is performing. For reservations, you can select the following Compute Engine metrics:
Reserved: The number of reserved virtual machine (VM) instances in each reservation in the current project.
Used: The number of consumed VMs in each reservation in the current project.
After you select a metric, you can further filter or group the measurements of reservations' metric. For more information about the available filters for reservations, see Reservations filters in this document.
Reservations filters
You can use Monitoring filters to group or filter the time series data associated with one or more reservations. Specifically, when creating Monitoring dashboards or alerting policies, you can limit the time series data that they use by specifying one or more of the following labels:
Selector | Label name | Description |
---|---|---|
metadata.system
|
machine_type
|
The machine type specified in the reserved VMs for a reservation. |
metadata.system |
name |
The name of a reservation. |
metadata.system
|
state
|
The state of a reservation. You can
only monitor reservations in the
ACTIVE state, which is when a
reservation exists. |
metric
|
reserved_resource_type
|
The type of reserved zonal
resources by a reservation. You can
only monitor the instance type,
which is a VM instance. |
resource
|
location
|
The zone where a reservation is located. |
resource
|
reservation_id
|
The identifier (ID) of a reservation. |
resource
|
resource_container
|
The project number of the project where a reservation exists. You can only monitor the reservations that were created in the current project. |
When creating a filter, you must specify the selector and the label name,
followed by a
comparison operator, and
then the value to filter. For example, if you want your query to filter your
reservations by zone us-central1-a
, use the following filter:
resource.location = "us-central1-a"
To ensure that the value you specify in a filter matches the value of a reservation's field, view the details of the reservation.
Monitor consumption of reservations
To monitor the consumption of your reservations, select one of the following methods specified in this document:
Create a dashboard—create Monitoring dashboards and add widgets to the graph areas to display the time series data tied to the consumption of your reservations.
This method is useful when, for example, you want to verify that a VM is correctly consuming a reservation or compare the consumption trend of multiple reservations.
Create alerting policies—create alerting policies to send alerts when the time series data tied to the consumption of your reservations reaches a defined threshold.
This method is useful when, for example, you want to be notified when the number of VMs used in the current project is below a specific ratio, or when a reservation remains unused for a specific amount time.
Create a dashboard
You can create Monitoring dashboards and view the time series tied to the consumption of your reservations by using the Google Cloud console (recommended) and Monitoring API.
When defining how to display the time series data of a Monitoring filter, you must use one of the following methods:
Basic Query: this method is useful to quickly configure the time series data for a dashboard widget.
For example, you can use Basic Query to quickly display which one of your reservations in a specific zone isn't fully consumed yet.
MQL: this method is useful to retrieve, filter, and manipulate time series data to create more complex configurations for a dashboard widget.
For example, you can use Monitoring Query Language (MQL) to display the ratio of consumed VMs to reserved VMs in your reservations.
Basic Query
The following example describes how to create a Monitoring
dashboard with a line chart widget to display your consumed reservations in
the us-central1-a
zone.
Console
To create a Monitoring dashboard using Basic Query, follow these steps:
In the Google Cloud console, go to Dashboards.
Click
Create dashboard.The New dashboard page opens.
Click
Add widget.The Add widget pane appears.
Click one of the available widgets. For example, click the Line widget.
The Configure widget pane appears.
Click Select a metric.
In the Select a metric window, do the following:
Enter
Reservation
, and then select Reservation.In the Active metrics categories list, select Reservation again.
In the Active metrics list, select one of the available metrics. For example, select Used.
Click Apply.
To filter your reservations by a specific zone, do the following:
In the Add filter list, select one of the available filters for reservations. For this example, select location.
In the Comparator list, select one of the available operators. For this example, select = (equals) (default).
In the Value list, select the zone you want to use to filter your reservations. For this example, select us-central1-a.
Click Apply.
For more options to customize Monitoring dashboards using the Google Cloud console, see Create and manage custom dashboards.
REST
To create a Monitoring dashboard using Basic Query, make a
POST
request to the
dashboards.create
method.
POST https://monitoring.googleapis.com/v1/projects/PROJECT_ID/dashboards
{
"displayName": "Consumed reservations in zone us-central1-a",
"mosaicLayout": {
"columns": 12,
"tiles": [
{
"height": 4,
"widget": {
"title": "Reservation - Used for us-central1-a [MEAN]",
"xyChart": {
"chartOptions": {
"mode": "COLOR"
},
"dataSets": [
{
"minAlignmentPeriod": "60s",
"plotType": "LINE",
"targetAxis": "Y1",
"timeSeriesQuery": {
"timeSeriesFilter": {
"aggregation": {
"alignmentPeriod": "60s",
"perSeriesAligner": "ALIGN_MEAN"
},
"filter": "FILTER",
"secondaryAggregation": {
"alignmentPeriod": "60s",
"perSeriesAligner": "ALIGN_NONE"
}
}
}
}
],
"timeshiftDuration": "0s",
"yAxis": {
"scale": "LINEAR"
}
}
},
"width": 6
}
]
}
}
Replace the following:
PROJECT_ID
: the project ID of the current project.FILTER
: the Monitoring filter to use for your dashboard. For example, to monitor the consumed reservations in zoneus-central1-a
, specify the following:resource.type = 'compute.googleapis.com/Reservation' AND metric.type = 'compute.googleapis.com/reservation/used' AND resource.location = 'us-central1-a'
For more options to customize Monitoring dashboards using the Monitoring API, see Create and manage dashboards by using the API.
MQL
The following example describes how to create a Monitoring dashboard with a line chart widget to display the ratio of used VMs to reserved VMs in your reservations.
Console
To create a Monitoring dashboard using MQL, follow these steps:
In the Google Cloud console, go to Dashboards.
Click
Create dashboard.The New dashboard page opens.
Click
Add widget.The Add widget pane appears.
Click one of the available widgets. For example, click the Line widget.
The Configure widget pane appears.
Click
MQL.In the Query editor, enter an MQL query. For example, to view the ratio of used VMs to reserved VMs in your reservations, specify the following:
fetch compute.googleapis.com/Reservation | { metric compute.googleapis.com/reservation/used | group_by [metadata.system.name], sliding(1m), max(value.used) ; metric compute.googleapis.com/reservation/reserved | group_by [metadata.system.name], sliding(1m), max(value.reserved) } | ratio
Click Run query.
Click Apply.
For more options to customize Monitoring dashboards using the Google Cloud console, see Create and manage custom dashboards.
REST
To create a Monitoring dashboard using MQL, make a POST
request to the
dashboards.create
method.
POST https://monitoring.googleapis.com/v1/projects/PROJECT_ID/dashboards
{
"displayName": "Consumed reservations in zone us-central1-a",
"mosaicLayout": {
"columns": 12,
"tiles": [
{
"height": 4,
"widget": {
"title": "Reservation - Used for us-central1-a [MEAN]",
"xyChart": {
"chartOptions": {
"mode": "COLOR"
},
"dataSets": [
{
"plotType": "LINE",
"targetAxis": "Y1",
"timeSeriesQuery": {
"timeSeriesQueryLanguage": "MQL_QUERY"
}
}
],
"timeshiftDuration": "0s",
"yAxis": {
"scale": "LINEAR"
}
}
},
"width": 6,
"xPos": 6
}
]
}
}
Replace the following:
PROJECT_ID
: the project ID of the current project.MQL_QUERY
: the MQL query to use for the line chart widget. For example, to view the ratio of used VMs to reserved VMs in your reservations, specify the following:fetch compute.googleapis.com/Reservation | { metric compute.googleapis.com/reservation/used | group_by [metadata.system.name], sliding(1m), max(value.used) ; metric compute.googleapis.com/reservation/reserved | group_by [metadata.system.name], sliding(1m), max(value.reserved) } | ratio
For more options to customize Monitoring dashboards using the Monitoring API, see Create and manage dashboards by using the API.
Create alerting policies
You can create Monitoring alerting policies to receive notifications about the reservations consumption in the current project by using the Google Cloud console and Monitoring API.
When defining an alert condition for an alerting policy, you must use one of the following methods:
Basic Query: this method is useful to create simple alert conditions.
For example, you can use Basic Query to create an alert condition that gets triggered whenever a reservation is consumed for the first time.
MQL: this method is useful to retrieve, filter, and manipulate time series data to create more complex alert conditions.
For example, you can use Monitoring Query Language (MQL) to create an alert condition that gets triggered when the ratio of reserved VMs to consumed VMs reaches a specific threshold.
Basic Query
The following example creates an alerting policy that sends an alert
notification when a reservation is consumed for the first time. Specifically,
the alert triggers whenever the number of consumed VMs in a reservation is
greater than 0
.
Console
To create a Monitoring alerting policy using Basic Query, follow these steps:
In the Google Cloud console, go to Alerting.
Click
Create policy.The Create alerting policy page opens.
Click
Select a metric.The Select a metric window appears.
In the Select a metric window, do the following:
In the Filter by resource or metric name field, enter
Reservation
.If the Reservation metric appears in the Active resources list, select it. Otherwise, do the following:
Clear Show only active resources & metrics.
The Inactive resources list appears.
In the Inactive resources list, select Reservation.
In the Active metrics categories list, select Reservation again.
The Active metrics list appears.
In the Active metrics list, select one of the available metrics.
For example, select Used.
Click Apply.
Click
Add filter.The Add filter section appears.
In the Add filter section, do the following:
In the Label list, select one of the available filters for reservations specified in this document.
For example, to filter your reservations by name, select name.
In the Comparison list, select one of the available operators.
For example, select = (equals) (default).
In the Value list, select the name of the reservation that you want to monitor.
Click Done.
Click Next.
The Configure alert trigger pane appears.
In the Condition types section, select one of the following options:
To trigger the condition if a time series falls above or below a specific value, select Threshold.
To trigger the condition if a time series doesn't have data for a specific time, select Metric absence.
To trigger the condition if a time series is projected to cross the threshold in the near future, select Forecast.
For example, select Threshold (default).
In the Alert trigger list, select the condition that triggers the alert.
For example, select Any time series violation (default).
In the Threshold position list, select when the condition triggers.
For example, select Above threshold.
In the Threshold value field, enter a value for the condition.
For example, enter
0
.In the Condition name field, enter a name for your condition.
For example, enter
Reservation RESERVATION_NAME consumed.
Where RESERVATION_NAME is the name of the reservation that you specified in the previous steps.
Click Next.
The Configure notifications and finalize alert pane appears.
Click Use notification channels.
In the Notification channels field, select the channels on which you want to be notified about the incident.
If you have no notification channels available, click Manage notification channels, and then follow the steps to create notification channels. For more information, see Create and manage notification channels.
In the Incident autoclose duration field, select a duration after which an incident is automatically closed.
For example, select 3 days.
In the Alert policy name field, enter a name for the alerting policy.
For example, enter
Alert: you started consuming reservation RESERVATION_NAME!
Where RESERVATION_NAME is the name of the reservation that you specified in the previous steps.
Click Next.
The review page of your alerting condition opens.
Click Create policy.
Creating the alerting policy might take a few seconds to complete. This action redirects you to the Create alerting policy page.
For more information about the options you have when creating alerting policies using the Google Cloud console and Basic Query, see Create metric-based alert policies.
REST
To create a Monitoring alerting policy using Basic Query,
make a POST
request to the
projects.alertPolicies.create
method.
POST https://monitoring.googleapis.com/v3/projects/PROJECT_ID/alertPolicies
{
"displayName": "Alert: you started consuming reservation RESERVATION_NAME!",
"conditions": [
{
"displayName": "Reservation RESERVATION_NAME consumed.",
"conditionThreshold": {
"filter": "FILTER",
"aggregations": [
{
"alignmentPeriod": "300s",
"crossSeriesReducer": "REDUCE_NONE",
"perSeriesAligner": "ALIGN_MEAN"
}
],
"comparison": "COMPARISON_GT",
"duration": "0s",
"trigger": {
"count": 1
},
"thresholdValue": 0
}
}
],
"alertStrategy": {
"autoClose": "AUTO_CLOSE_TIME"
},
"combiner": "OR",
"enabled": true,
"notificationChannels": [
"projects/PROJECT_ID/notificationChannels/NOTIFICATION_CHANNEL"
]
}
Replace the following:
PROJECT_ID
: the project ID of the current project.RESERVATION_NAME
: the name of an existing reservation which is located in the current project.FILTER
: the Monitoring filter to use for your alerting policy. For example, to monitor theused
metric for the RESERVATION_NAME reservation, specify the following:resource.type = 'compute.googleapis.com/Reservation' AND metric.type = 'compute.googleapis.com/reservation/used' AND metadata.system.name = 'RESERVATION_NAME'
AUTO_CLOSE_TIME
: the time in seconds before an incident is automatically closed. The value must be between0s
and604800s
(7 days). For example, enter259200s
(3 days).NOTIFICATION_CHANNEL
: the name of an existing notification channel. To set up a notification channel, see Create and manage notification channels.
For more information about the options you have when creating alerting policies using the Monitoring API and Basic Query, see Create alerting policies by using the API.
MQL
The following example creates an alerting policy that sends an alert notification whenever the percentage of used VMs to reserved VMs in your reservations is above 90%.
Console
To create a Monitoring alerting policy using MQL, follow these steps:
In the Google Cloud console, go to Alerting.
Click
Create policy.The Create alerting policy page opens.
On the toolbar, click MQL.
The Edit query pane appears.
In the Edit query pane, enter an MQL query.
For example, to create a query that groups your reservations by name and triggers an alert condition when over 90% of your reservations are consumed, enter the following query:
fetch compute.googleapis.com/Reservation | { metric compute.googleapis.com/reservation/used | group_by [metadata.system.name], sliding(1m), max(value.used) ; metric compute.googleapis.com/reservation/reserved | group_by [metadata.system.name], sliding(1m), max(value.reserved) } | ratio | every 1m | condition gt(val(), 0.9)
To run the query you've just entered, click Run query.
Click Next.
The Configure alert trigger pane appears.
If the Condition name, enter a name for your condition.
For example, enter
Over 90% of your reservations are consumed.
Click Next again.
The Configure notifications and finalize alert pane appears.
Click Use notification channels.
In the Notification channels field, select the channels on which you want to be notified about the incident.
If you have no notification channels available, click Manage notification channels, and then follow the steps to create notification channels. For more information, see Create and manage notification channels.
In the Incident autoclose duration field, select a duration after which an incident is automatically closed.
For example, select 3 days.
In the Alert policy name field, enter a name for the alerting policy.
For example, enter
Alert: over 90% of your reservations are consumed.
Click Next.
The review page of your alerting condition opens.
Click Create policy.
Creating the alerting policy might take a few seconds to complete. This action redirects you to the Create alerting policy page.
For more information about creating alerting policies using the Google Cloud console and MQL, see Create MQL alerting policies (console).
REST
To create a Monitoring alerting policy using MQL, make a
POST
request to the
projects.alertPolicies.create
method.
POST https://monitoring.googleapis.com/v3/projects/PROJECT_ID/alertPolicies
{
"displayName": "Alert: over 90% of your reservations are consumed.",
"conditions": [
{
"displayName": "Over 90% of your reservations are consumed.",
"conditionMonitoringQueryLanguage": {
"duration": "0s",
"trigger": {
"count": 1
},
"query": "MQL_QUERY"
}
}
],
"alertStrategy": {
"autoClose": "AUTO_CLOSE_TIME"
},
"combiner": "OR",
"enabled": true,
"notificationChannels": [
"projects/PROJECT_ID/notificationChannels/NOTIFICATION_CHANNEL"
]
}
Replace the following:
PROJECT_ID
: the project ID of the current project.MQL_QUERY
: an MQL query to use for the alerting policy. For example, to create a query that tracks when the percentage of used VMs to reserved VMs is above 90% in the current project's reservations, specify the following:fetch compute.googleapis.com/Reservation | { metric compute.googleapis.com/reservation/used | group_by [metadata.system.name], sliding(1m), max(value.used) ; metric compute.googleapis.com/reservation/reserved | group_by [metadata.system.name], sliding(1m), max(value.reserved) } | ratio | every 1m | condition gt(val(), 0.9)
AUTO_CLOSE_TIME
: the time in seconds before an incident is automatically closed. The value must be between0s
and604800s
(7 days). For example, enter259200s
(3 days).NOTIFICATION_CHANNEL
: the name of an existing notification channel. To set up a notification channel, see Create and manage notification channels.
For more information about creating alerting policies using the Monitoring API and MQL, see Create MQL alerting policies (API).
Troubleshoot
Learn how to troubleshoot issues with reservation monitoring.
What's next
Learn how to consume reservations.
Learn how to attach reservations to commitments.
Learn how to modify reservations.
Learn how to delete reservations.