Monitor consumption of reservations

This document explains how to monitor the consumption ofreservations of Compute Engine zonal resourcesby using Cloud Monitoring.

Monitoring collects andstores performance information of Google Cloud services such asCompute Engine. The performance information is calledmetrics and time series. Youcan access the metrics and time series of your Compute Enginereservations to do the following:

These methods can, for example, help you verify that your reservations are beingconsumed as you planned or timely act to avoid unnecessary costs from wastedresources or unused reservations.

Before you begin

Required roles

To get the permissions that you need to create Monitoring dashboards or alertingpolicies to monitor the consumption of reservations, ask your administrator to grant you theMonitoring Admin (roles/monitoring.admin) IAM role on the project. For more information about granting roles, seeManage access to projects, folders, and organizations.

This predefined role contains the permissions required to create Monitoring dashboards or alertingpolicies to monitor the consumption of reservations. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

The following permissions are required to create Monitoring dashboards or alertingpolicies 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 withcustom roles or otherpredefined roles.

Restrictions

When using Monitoring to access and view thetime series of a reservation, the followingrestrictions apply:

  • After you create a reservation, its time series becomes available within 30minutes.

  • After a time series becomes available, Monitoring startsupdating it at least once every 30 minutes.

  • If you delete a reservation, its time series is also deleted and can't berecovered.

  • You can only access and view the time series of a reservation that was createdin the current project.

For more information about Monitoring restrictions, seeCloud Monitoring quotas and limits.

Reservations metrics

When creating Monitoring dashboards or alerting policies, youmust first select theGoogle Cloud metric to measurehow the Google Cloud service is performing. For reservations, you canselect the following Compute Engine metrics:

  • Reserved: The number of reserved virtual machine (VM) instances in eachreservation in the current project.

  • Used: The number of consumed VMs in each reservation in the currentproject.

After you select a metric, you can further filter or group the measurements ofreservations' metric. For more information about the available filters forreservations, seeReservations filters in this document.

Reservations filters

You can useMonitoring filters togroup or filter the time series data associated with one or more reservations.Specifically, when creating Monitoring dashboards or alertingpolicies, you can limit the time series data that they use by specifying one ormore of the following labels:

SelectorLabel nameDescription
metadata.systemmachine_typeThe machine type specified in the reserved VMs for a reservation.
metadata.systemnameThe name of a reservation.
metadata.systemstateThe state of a reservation. You can only monitor reservations in theACTIVE state, which is when a reservation exists.
metricreserved_resource_typeThe type of reserved zonal resources by a reservation. You can only monitor theinstance type, which is a VM instance.
metricservice_name

When you select theUsed metric in the Google Cloud console, you can view which Google Cloud product consumes the reservation. The value can be one of the following:

  • COMPUTE_ENGINE: VMs in Compute Engine
  • VERTEX_ONLINE_PREDICTION: VMs in Vertex AI prediction jobs
  • VERTEX_TRAINING: VMs in Vertex AI custom training jobs

If you consume reservations both in Compute Engine and Vertex AI, then create a filter for each preceding value.

resourcelocationThe zone where a reservation is located.
resourcereservation_idThe identifier (ID) of a reservation.
resourceresource_containerThe project number of the project where a reservation exists. You can only monitor the reservations that were created in your project.

When creating a filter, you must specify the selector and the label name,followed by acomparison operator, andthen the value to filter. For example, if you want your query to filter yourreservations by zoneus-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 areservation's field,view the details of the reservation.

Note: To view a reservation ID, view the details of the reservation using theGoogle Cloud CLI or REST.

Monitor consumption of reservations

To monitor the consumption of your reservations, select one of the followingmethods specified in this document:

  • Create a dashboard—create Monitoringdashboards and add widgets to the graph areas to display the time series datatied to the consumption of your reservations.

    This method is useful when, for example, you want to verify that a VM iscorrectly consuming a reservation or compare the consumption trend of multiplereservations.

  • Create alerting policies—create alertingpolicies to send alerts when the time series data tied to the consumption ofyour reservations reaches a defined threshold.

    This method is useful when, for example, you want to be notified when thenumber of VMs used in the current project is below a specific ratio, or when areservation remains unused for a specific amount time.

Create a dashboard

You can createMonitoring dashboardsand view the time series tied to the consumption of your reservations by usingthe Google Cloud console (recommended) and Monitoring API.

When defining how to display the time series data of a Monitoringfilter, you must use one of the following methods:

  • Basic Query: this method is useful to quickly configure the time seriesdata for a dashboard widget.

    For example, you can use Basic Query to quickly display which one of yourreservations in a specific zone isn't fully consumed yet.

  • PromQL: this method is useful to retrieve, filter, and manipulate timeseries data to create more complex configurations for a dashboard widget.

    For example, you can usePromQL in Cloud Monitoringto display the ratio of consumed VMs to reserved VMs in your reservations.

Basic Query

The following example describes how to create a Monitoringdashboard with a line chart widget to display your consumed reservations intheus-central1-a zone.

Console

To create a Monitoring dashboard using Basic Query, followthese steps:

  1. In the Google Cloud console, go toDashboards.

    Go to Dashboards

  2. ClickCreate dashboard.

    TheNew dashboard page opens.

  3. ClickAdd widget.

    TheAdd widget pane appears.

  4. Click one of the available widgets. For example, click theLinewidget.

    TheConfigure widget pane appears.

  5. ClickSelect a metric.

  6. In theSelect a metric window, do the following:

    1. EnterReservation, and then selectReservation.

      Important: If you can't see theReservation metric, seeMetric not listed in menu.

    2. In theActive metrics categories list, selectReservationagain.

    3. In theActive metrics list, select one of the available metrics.For example, selectUsed.

    4. ClickApply.

  7. To filter your reservations by a specific zone, do the following:

    1. In theAdd filter list, select one of the availablefilters for reservations. For this example,selectlocation.

    2. In theComparator list, select one of the available operators.For this example, select= (equals) (default).

    3. In theValue list, select the zone you want to use to filteryour reservations. For this example, selectus-central1-a.

  8. ClickApply.

For more options to customize Monitoring dashboards usingthe Google Cloud console, seeCreate and manage custom dashboards.

REST

Note: After creating a dashboard using the Monitoring API,you can onlymanage it using the Google Cloud console.

To create a Monitoring dashboard using Basic Query, make aPOST request to thedashboards.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 currentproject.

  • FILTER: the Monitoring filterto use for your dashboard. For example, to monitor the consumedreservations in zoneus-central1-a, specify the following:

    resource.type='compute.googleapis.com/Reservation'ANDmetric.type='compute.googleapis.com/reservation/used'ANDresource.location='us-central1-a'

For more options to customize Monitoring dashboards usingthe Monitoring API, seeCreate and manage dashboards by using the API.

PromQL

The following example describes how to create a Monitoringdashboard with a line chart widget to display the ratio of used VMs toreserved VMs in your reservations.

Console

To create a Monitoring dashboard and add a widgetconfigured with a query using PromQL, follow these steps:

  1. In the Google Cloud console, go to the Dashboards page:

    Go toDashboards

    If you use the search bar to find this page, then select the result whose subheading isMonitoring.

  2. ClickCreate dashboard.

    TheNew dashboard page opens.

  3. ClickAdd widget.

    TheAdd widget pane appears.

  4. Click one of the available widgets. For example, click theLinewidget.

    TheConfigure widget pane appears.

  5. If you don't see the code editor, then clickPromQL orMQL. ForLanguage,selectPromQL.

  6. In the Query editor, enter a PromQL query. For example, to view theratio of used VMs to reserved VMs in your reservations, specify thefollowing:

    (maxby(metadata_system_name)({"compute.googleapis.com/reservation/used"})/maxby(metadata_system_name)({"compute.googleapis.com/reservation/reserved"}))

  7. ClickRun query.

  8. ClickApply.

For more options to customize Monitoring dashboards usingthe Google Cloud console, seeCreate and manage custom dashboards.

REST

Note: After creating a dashboard using the Monitoring API,you can onlymanage it using the Google Cloud console.

To create a Monitoring dashboard and add a widgetconfigured with a query using PromQL, make aPOST request to thedashboards.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": "PROMQL_QUERY"                }              }            ],            "timeshiftDuration": "0s",            "yAxis": {              "scale": "LINEAR"            }          }        },        "width": 6,        "xPos": 6      }    ]  }}

Replace the following:

For more options to customize Monitoring dashboards usingthe Monitoring API, seeCreate and manage dashboards by using the API.

Create alerting policies

You can createMonitoring alerting policiesto receive notifications about the reservations consumption in the currentproject by using the Google Cloud console and Monitoring API.

When defining an alert condition for an alerting policy, you must use one of thefollowing 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 getstriggered whenever a reservation is consumed for the first time.

  • PromQL: this method is useful to retrieve, filter, and manipulate time seriesdata to create more complex alert conditions.

    For example, you can usePrometheus Query Language (PromQL) to create an alertcondition that gets triggered when the ratio of reserved VMs to consumed VMsreaches a specific threshold.

Basic Query

The following example creates an alerting policy that sends an alertnotification when a reservation is consumed for the first time. Specifically,the alert triggers whenever the number of consumed VMs in a reservation isgreater than0.

Console

To create a Monitoring alerting policy using Basic Query,follow these steps:

  1. In the Google Cloud console, go toAlerting.

    Go to Alerting

  2. ClickCreate policy.

    TheCreate alerting policy page opens.

  3. ClickSelect a metric.

    TheSelect a metric window appears.

  4. In theSelect a metric window, do the following:

    1. In theFilter by resource or metric name field, enterReservation.

    2. If theReservation metric appears in theActive resourceslist, select it. Otherwise, do the following:

      1. ClearShow only active resources & metrics.

        TheInactive resources list appears.

      2. In theInactive resources list, selectReservation.

        Important: If you still can't see theReservation metric,seeMetric not listed in menu.

    3. In theActive metrics categories list, selectReservationagain.

      TheActive metrics list appears.

    4. In theActive metrics list, select one of the available metrics.

      For example, selectUsed.

    5. ClickApply.

  5. ClickAdd filter.

    TheAdd filter section appears.

  6. In theAdd filter section, do the following:

    1. In theLabel list, select one of the availablefilters for reservations specified in thisdocument.

      For example, to filter your reservations by name, selectname.

    2. In theComparison list, select one of the available operators.

      For example, select= (equals) (default).

    3. In theValue list, select the name of the reservation that youwant to monitor.

    4. ClickDone.

  7. ClickNext.

    TheConfigure alert trigger pane appears.

  8. In theCondition types section, select one of the followingoptions:

    1. To trigger the condition if a time series falls above or below aspecific value, selectThreshold.

    2. To trigger the condition if a time series doesn't have data for aspecific time, selectMetric absence.

    3. To trigger the condition if a time series is projected to cross thethreshold in the near future, selectForecast.

    For example, selectThreshold (default).

  9. In theAlert trigger list, select the condition that triggers thealert.

    For example, selectAny time series violation (default).

  10. In theThreshold position list, select when the condition triggers.

    For example, selectAbove threshold.

  11. In theThreshold value field, enter a value for the condition.

    For example, enter0.

  12. In theCondition name field, enter a name for your condition.

    For example, enterReservationRESERVATION_NAME consumed.

    WhereRESERVATION_NAME is the name of thereservation that you specified in the previous steps.

  13. ClickNext.

    TheConfigure notifications and finalize alert pane appears.

  14. ClickUse notification channels.

  15. In theNotification channels field, select the channels on whichyou want to be notified about the incident.

    If you have no notification channels available, clickManage notification channels, and then follow the steps to createnotification channels. For more information, seeCreate and manage notification channels.

  16. In theIncident autoclose duration field, select a duration afterwhich an incident is automatically closed.

    For example, select3 days.

  17. In theAlert policy name field, enter a name for the alertingpolicy.

    For example, enterAlert: you started consuming reservationRESERVATION_NAME!

    WhereRESERVATION_NAME is the name of thereservation that you specified in the previous steps.

  18. ClickNext.

    The review page of your alerting condition opens.

  19. ClickCreate policy.

    Creating the alerting policy might take a few seconds to complete. Thisaction redirects you to theCreate alerting policy page.

For more information about the options you have when creating alertingpolicies using the Google Cloud console and Basic Query, seeCreate metric-based alert policies.

REST

To create a Monitoring alerting policy using Basic Query,make aPOST request to theprojects.alertPolicies.create method.

POST https://monitoring.googleapis.com/v3/projects/PROJECT_ID/alertPolicies{  "displayName": "Alert: you started consuming reservationRESERVATION_NAME!",  "conditions": [    {      "displayName": "ReservationRESERVATION_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 currentproject.

  • RESERVATION_NAME: the name of an existingreservation which is located in the current project.

  • FILTER: the Monitoring filterto use for your alerting policy. For example, to monitor theusedmetric for theRESERVATION_NAMEreservation, specify the following:

    resource.type='compute.googleapis.com/Reservation'ANDmetric.type='compute.googleapis.com/reservation/used'ANDmetadata.system.name='RESERVATION_NAME'

  • AUTO_CLOSE_TIME: the time in seconds before anincident is automatically closed. The value must be between0s and604800s (7 days). For example, enter259200s (3 days).

  • NOTIFICATION_CHANNEL: the name of an existingnotification channel. To set up a notification channel, seeCreate and manage notification channels.

For more information about the options you have when creating alertingpolicies using the Monitoring API and Basic Query, seeCreate alerting policies by using the API.

PromQL

The following example creates an alerting policy that sends an alertnotification whenever the percentage of used VMs to reserved VMs in yourreservations is above 90%.

Console

To create a Monitoring alerting policy using PromQL, followthese steps:

  1. In the Google Cloud console, go toAlerting.

    Go to Alerting

  2. ClickCreate policy.

    TheCreate alerting policy page opens.

  3. ForPolicy configuration mode, selectCode editor (MQL or PromQL).

    TheQuery editor pane appears.

  4. SelectPromQL as the language, and enter a PromQL query.

    For example, to create a query that groups your reservations by nameand triggers an alert condition when over 90% of your reservations areconsumed, enter the following query:

    (maxby(metadata_system_name)({"compute.googleapis.com/reservation/used"})/maxby(metadata_system_name)({"compute.googleapis.com/reservation/reserved"})) >0.9

  5. ClickNext.

    TheConfigure alert trigger pane appears.

  6. If theCondition name, enter a name for your condition.

    For example, enterOver 90% of your reservations are consumed.

  7. ClickNext again.

    TheConfigure notifications and finalize alert pane appears.

  8. ClickUse notification channels.

  9. In theNotification channels field, select the channels on whichyou want to be notified about the incident.

    If you have no notification channels available, clickManage notification channels, and then follow the steps to createnotification channels. For more information, seeCreate and manage notification channels.

  10. In theIncident autoclose duration field, select a duration afterwhich an incident is automatically closed.

    For example, select3 days.

  11. In theAlert policy name field, enter a name for the alertingpolicy.

    For example, enterAlert: over 90% of your reservations are consumed.

  12. ClickNext.

    The review page of your alerting condition opens.

  13. ClickCreate policy.

    Creating the alerting policy might take a few seconds to complete. Thisaction redirects you to theCreate alerting policy page.

For more information about creating alerting policies using theGoogle Cloud console and PromQL, seeCreate PromQL-based alerting policies (Console).

REST

To create a Monitoring alerting policy using PromQL, make aPOST request to theprojects.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": "PROMQL_QUERY"      }    }  ],  "alertStrategy": {    "autoClose": "AUTO_CLOSE_TIME"  },  "combiner": "OR",  "enabled": true,  "notificationChannels": [    "projects/PROJECT_ID/notificationChannels/NOTIFICATION_CHANNEL"  ]}

Replace the following:

For more information about creating alerting policies using theMonitoring API and PromQL, seeCreate PromQL-based alerting policies (API).

Troubleshoot

Learn how totroubleshoot issues with reservation monitoring.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.