View usage and forecast data

This document explains how to view usage and forecast data for your resources in Capacity Planner. To learn more about Capacity Planner, see Capacity Planner overview.

You can view the usage and forecast data for the following resources:

  • Compute Engine instances, including vCPUs, memory, and Local SSD disks attached to the instances.

  • Hyperdisk and Persistent Disk volume storage, IOPS, and throughput, whether they are attached to instances or not.

  • GPUs, whether they are attached to instances or not.

  • TPUs

Usage data helps you optimize your resources usage, and plan for future capacity and quota needs in your project, folder, or organization.

Limitations

Before you view usage and forecast data in Capacity Planner, consider the following:

  • Forecasts don't support Spot VMs, and usage data for Spot VMs is only available as follows:

    • In the Google Cloud console, you can enable Spot VMs usage data in the Usage and forecast by machine family graph.
    • In the Capacity Planner API, you can enable Spot VMs usage data by setting the isSpot field to true.

  • The Usage and forecast by resource type graph has the following limitations:

    • You can only view quota for your compute instances, GPUs, or TPUs when you do all of the following:

      • You view usage and forecast data in your project.

      • You filter the graph by a single machine family, GPU type, or TPU type.

      • For instances and GPUs, you filter the graph by region. For TPUs, to view quota for Google Kubernetes Engine, filter the graph by region; to view quota for Cloud TPU, filter by zone.

    • You can only view reservations and future reservation requests when you do both of the following:

      • You view usage and forecast data for instances or GPUs.

      • You view usage and forecast data in the project where you created the reservations, the folder containing this project, or your organization.

  • You can only view the Usage and forecast by machine types table when you view usage and forecast data for instances or GPUs.

For more information, also see Data availability and updates in this document.

Before you begin

If you haven't used Capacity Planner before, review Capacity Planner overview and enable Capacity Planner by completing the prerequisites for projects and users.

Required roles

To get the permissions that you need to view the usage and forecast data of your resources, ask your administrator to grant you the Capacity Planner Usage Viewer (roles/capacityplanner.viewer) IAM role on your project, folder, or organization. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to view the usage and forecast data of your resources. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to view the usage and forecast data of your resources:

  • To view forecast data: capacityplanner.forecasts.list on the project, folder, or organization
  • To view historical usage data: capacityplanner.usageHistories.list on the project, folder, or organization
  • To summarize the historical usage data: capacityplanner.usageHistories.summarize on the project, folder, or organization

You might also be able to get these permissions with custom roles or other predefined roles.

Data availability and updates

When you view usage and forecast data in Capacity Planner, consider the following:

  • Capacity Planner data is available as follows:

    • Historical usage data: historical usage data is available for up to the past two years with the following exceptions:

      • For reservations, historical usage data isn't available before August 1, 2024.

      • For future reservation requests, usage data is only available for up to one year after the start of its reservation period.

    • Forecast data: you can view forecast data up to six months in the future.

  • Capacity Planner data is updated as follows:

    • Capacity Planner samples historical usage data every five minutes and displays the data within 24 hours after usage.

    • On the Overview Google Cloud console page, data in the Insights section updates at least once every 48 hours.

View the forecast and usage of your resources

View the usage and forecast data about the compute instances, Persistent Disk volumes, GPUs, and TPUs in your project, folder, or organization by using the following methods:

View the forecast and usage of your resources using the Google Cloud console

To view the forecast and usage of your resources using the Google Cloud console, complete the following steps.

  1. In the Google Cloud console, open Capacity Planner.

    Go to Capacity Planner

    The Overview page appears.

  2. Optional: To change the scope (project, folder, or organization) that you want to view data for, do the following:

    1. On the Google Cloud console toolbar, click the resource selector.
    2. In the Select a resource dialog that appears, select a project, folder, or organization.

  3. On the Overview page, you can view data that summarizes overall resource usage, including potential action items and the regional distribution of your resources as follows:

    • The Insights section summarizes overall resource usage and highlights data that indicates potential action items.

      For example, the Active regions metric shows the total number of regions that your project, folder, or organization has resources in; this metric might help you understand the overall size and growth of your workloads. Additionally, the Fastest growing resource metric shows the resource with the largest positive percent change in usage in the last 30 days compared to the 30 days before that.

    • The Region and resource distribution chart shows the number of resources that you have in each region for each resource type in the last 30 days. To filter the chart, use the Resource list and then the Resource type list to select a resource metric.

      Notably, this chart doesn't include Spot VMs usage. Additionally, if there are more than 5 regions for the selected resource metric in the last 30 days, then only the top 5 regions for the metric are listed, and the remaining regions specified as Other.

  4. To view usage and forecast data for specific types of resources in specific regions and zones, review the pages in the Usage & forecast section as follows:

    1. In the Usage & forecast section of the Capacity Planner navigation menu, select a page based on the type of resource that you want to view data for:

      • To view data for instances, open the Virtual machine page.

      • To view data for Hyperdisk and Persistent Disk volumes, open the Disk page.

      • To view data for GPUs, open the GPU page.

      • To view data for TPUs, open the TPU page.

    2. To learn about the tables and graphs on the Usage & forecast pages, see the following sections:

Usage and forecast by resource type

When you view the Usage & forecast pages, Capacity Planner provides graphs that show usage trends (50th, 75th, or 99th percentile) and forecasts (lower bound, upper bound, and median) for your compute instances, Persistent Disk volumes, GPUs, or TPUs. The graph that you see depends on the resource that you're viewing:

  • Usage and forecast by machine family or Usage and forecast by machine type: This graph shows the usage, forecast, reservations (if any), and quota of the Local SSD disks, memory, or vCPUs of your instances, filtered by both of the following:

    • Machine family or machine type

    • Location

  • Usage and forecast by disk type: This graph shows the history, forecast, and quota for your Hyperdisk and Persistent Disk volumes, filtered by the following:

    • Disk type
    • Confidentiality mode, which only appears if you use confidential mode for Hyperdisk balanced
    • Location
    • Resource type, which is one of the following:
      • Storage
      • IOPS
      • Throughput

  • Usage and forecast by GPU type: This graph shows the usage, forecast, reservations (if any), and quota for your GPUs, filtered by GPU type and location.

  • Usage and forecast by TPU type: This graph shows the usage, forecast, and quota for your TPUs, filtered by TPU version and location.

By default, the Usage and forecast by machine family graph showing the most used machine family and region in the last 30 days appears. This graph also shows the following:

  • The 99th percentile usage for your instances.

  • The upper bound of a prediction interval of 50.

  • Any reservations or future reservation requests as follows:

    • In a project or folder, you can see single-project reservations.

    • In an organization, you can see single-project and shared reservations.

  • Spot VMs usage and preemptible quota. If you don't see Spot VMs usage, you must show the option in the graph, through "More Options", as described in the following section.

If you are viewing usage and forecast data of a resource in your project, and your project has sufficient usage data, the Enable quota adjuster button appears. Click it to enable the quota adjuster in your project.

Show or hide data in the graph

To show or hide options in the graph, click More options, and then click the respective toggles to the on or off position. Capacity Planner updates the calculated future reservations data every 60 minutes.

Usage and forecast by machine types

When you view the Virtual Machines page or GPUs page, the Usage and forecast by machine types table shows historical and forecasted usage for the following resources:

  • When you view the usage data of your compute instances, the table shows the forecasted usage for a selected machine family and location. This table doesn't include Spot VMs usage.

  • When you view the usage data of your GPUs, the table shows the forecasted usage for a selected GPU type and location.

Capacity Planner presents data as follows:

  • At the 50th, 75th, or 99th percentile.

  • Broken down by individual machine type and zone.

  • Filtered by instances, CPU cores (if applicable), or GPUs (if applicable).

The table includes the following columns:

  • Machine type: the details of each machine type in the selected machine family, including vCPUs, memory, attached Local SSD disks (if any), and GPU type (if any).

  • Zone: the zone where each machine type is located.

  • Max of NTH percentile RESOURCE usage: the maximum number of instances that used each machine type, calculated using your selected percentile.

  • Max of NTH forecast MONTH: the maximum number of instances that are expected to use each machine type in a specific month, calculated using your selected percentile. The table contains a separate column for up to six months in the future.

  • Reservations: the existing reservations, as well as past and existing future reservation requests. The table shows the data broken down by machine type and zone, and calculated using your selected percentile. If there are reservations or future reservation requests for a specific machine type and zone, click the Details button. A pane appears showing the following:

    • In the Usage by CPU platform section, the percentage breakdown of minimum CPU platforms for that machine type and zone.

    • In the VM forecast for date range section, the forecast number of instances over your selected date range for the selected percentile usage.

    • In the Reservations by CPU platform section, the existing reservations and future reservation requests grouped by CPU platform.

Except for the percentage breakdown by machine type, Capacity Planner rounds all values to the nearest whole number.

By default, the table shows the 99th percentile usage and a prediction interval of 50% for the most used machine type in the most active location over the past 30 days. To view the future reservation requests during your chosen forecast dates, click Future reservations in forecast range.

View the forecast and usage of your resources using the Capacity Planner API

To view the forecast and usage of your resources using the Capacity Planner API, make a request to one or more of the REST methods in the following table. These methods are helpful when you want to query data programmatically. For more information about the available data, also see View the forecast and usage of your resources using the Google Cloud console.

REST methods
Query historical usage timeseries
Query forecast timeseries
Query reservations timeseries

What's next