Enable the PMU in VMs

This document explains how to enable the performance monitoring unit (PMU) innew or existing virtual machine (VM) instances. To learn more about the PMU, seePMU overview.

After you enable the PMU in a C4A or C4 VM and connect to it, you can run andinstall performance-monitoring software on the VM to analyze and optimize theperformance of the software running on the VM. This approach is useful whenrunning performance-sensitive workloads, such as high performance computing(HPC) or machine learning (ML) workloads.

Before you begin

Required roles

To get the permissions that you need to enable the PMU in a new or existing VM, ask your administrator to grant you theCompute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on your project. For more information about granting roles, seeManage access to projects, folders, and organizations.

This predefined role contains the permissions required to enable the PMU in a new or existing VM. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

The following permissions are required to enable the PMU in a new or existing VM:

  • To create VMs:
    • compute.instances.create on the project
    • To use a custom image to create the VM:compute.images.useReadOnly on the image
    • To use a snapshot to create the VM:compute.snapshots.useReadOnly on the snapshot
    • To use an instance template to create the VM:compute.instanceTemplates.useReadOnly on the instance template
    • To assign alegacy network to the VM:compute.networks.use on the project
    • To specify a static IP address for the VM:compute.addresses.use on the project
    • To assign an external IP address to the VM when using a legacy network:compute.networks.useExternalIp on the project
    • To specify a subnet for the VM:compute.subnetworks.use on the project or on the chosen subnet
    • To assign an external IP address to the VM when using a VPC network:compute.subnetworks.useExternalIp on the project or on the chosen subnet
    • To set VM instance metadata for the VM:compute.instances.setMetadata on the project
    • To set tags for the VM:compute.instances.setTags on the VM
    • To set labels for the VM:compute.instances.setLabels on the VM
    • To set a service account for the VM to use:compute.instances.setServiceAccount on the VM
    • To create a new disk for the VM:compute.disks.create on the project
    • To attach an existing disk in read-only or read-write mode:compute.disks.use on the disk
    • To attach an existing disk in read-only mode:compute.disks.useReadOnly on the disk
  • To create an instance template:compute.instanceTemplates.create on the project
  • To update a VM:compute.instances.update on the VM

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Enable the PMU in VMs

To enable the PMU in one or more C4A or C4 VMs, use one of the followingmethods:

After you've enabled the PMU in one or more VMs, you can install and useperformance-monitoring software on the VMs.

Enable the PMU in an existing VM

Before enabling the PMU in an existing VM, make sure that the VM uses asupported machine type and CPU platformby doing the following:

  1. To verify the machine type and CPU platform of the VM,view the details of the VM.

  2. If you need to change the machine type of the VM, then do the following:

    1. To verify that a supported CPU platform is available in the zone wherethe VM is located, seeAvailable regions and zones.

      Note: If a supported CPU platform is not available in the zone of theVM, then you mustmigrate the VM to a different zoneorcreate a new VM that has the PMU enabled.

    2. Change the machine typeas follows:

      • To enable the Enhanced PMU type, you must specify aC4 machine typewith 144 or 288 vCPUs.

      • Otherwise, to enable the Architectural or Standard PMU type, specifyany C4A or C4 machine type.

You don't have to stop the VM to enable the PMU. However, to make the changeeffective, you must restart the VM as described in this section.

To enable the PMU in an existing VM, select one of the following options:

gcloud

  1. Create an empty YAML file.

  2. To export the properties of a VM into the YAML file that you've justcreated, use thegcloud compute instances export command:

    gcloud compute instances exportVM_NAME \    --destination=YAML_FILE \    --zone=ZONE

    Replace the following:

    • VM_NAME: the name of the VM.

    • YAML_FILE: the path to the YAML file that youcreated in the previous step.

    • ZONE: the zone where the VM is located.

  3. In the YAML configuration file, add theperformanceMonitoringUnitfield. If theadvancedMachineFeatures field doesn't exist, then add itas well:

    advancedMachineFeatures:  performanceMonitoringUnit:PMU_TYPE

    ReplacePMU_TYPE with one of the following values:

    • Architectural PMU type:ARCHITECTURAL

    • Standard PMU type:STANDARD

    • Enhanced PMU type:ENHANCED

    Tip: To avoid getting an error such as"ERROR: (gcloud.compute.instances.update-from-file) Cannot parse YAML: [Expected type for field value, found True (type)]", add quotes (' ') around any label values ofyes orno in the exported instance configuration file. This indicates the values are strings, not Boolean values.

  4. To update the VM and restart it, use thegcloud compute instances update-from-file commandwith the--most-disruptive-allowed-action flag set toRESTART:

    gcloud compute instances update-from-fileVM_NAME \    --most-disruptive-allowed-action=RESTART \    --source=YAML_FILE \    --zone=ZONE

    Replace the following:

    • VM_NAME: the name of the VM.

    • YAML_FILE: the path to the YAML file with theconfiguration data that you modified in the previous step.

    • ZONE: the zone where the VM is located.

REST

  1. Create an empty JSON file.

  2. To view the properties of an existing VM, make aGET request to theinstances.get method:

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME

    Replace the following:

    • PROJECT_ID: the ID of the project where the VM islocated.

    • ZONE: the zone where the VM is located.

    • VM_NAME: the name of an existing VM.

  3. In the empty JSON file that you created in the previous steps, do thefollowing:

    1. Enter the VM properties from theGET request output.

    2. In theadvancedMachineFeatures field, add theperformanceMonitoringUnit field. If theadvancedMachineFeaturesfield doesn't exist, then add it as well:

      {  "advancedMachineFeatures": {    "performanceMonitoringUnit": "PMU_TYPE"  },  ...}

      ReplacePMU_TYPE with one of the followingvalues:

      • Architectural PMU type:ARCHITECTURAL

      • Standard PMU type:STANDARD

      • Enhanced PMU type:ENHANCED

  4. To update the VM and restart it, make aPUT request to theinstances.update method.In the request, do the following:

    • In the request URL, include themostDisruptiveAllowedAction queryparameter set toRESTART.

    • For the request body, use the VM properties from the JSON file thatyou created and updated in the previous steps.

    The request is similar to the following:

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME?mostDisruptiveAllowedAction=RESTART{  "advancedMachineFeatures": {    "performanceMonitoringUnit": "PMU_TYPE"  },  ...}

For more information about updating the properties of a VM, seeUpdate instance properties.

Enable the PMU while creating a VM

You can only create a VM that has the PMU enabled in a zone that contains asupported CPU platform. For a list ofavailable CPUs by zone, seeAvailable regions and zones.

To create a VM that has the PMU enabled, select one of the following options:

gcloud

To create a VM that has the PMU enabled, use thegcloud compute instances create commandwith the--performance-monitoring-unit flag:

gcloud compute instances createVM_NAME \    --machine-type=MACHINE_TYPE \    --performance-monitoring-unit=PMU_TYPE \    --zone=ZONE

Replace the following:

  • VM_NAME: the name of the VM.

  • MACHINE_TYPE: aC4A orC4 machine type.If you try to enable PMU on a VM that doesn't use asupported machine type,then the VM creation operation fails.

  • PMU_TYPE: the type of PMU to enable in the VM.Specify one of the following values:

    • Architectural PMU type:architectural

    • Standard PMU type:standard

    • Enhanced PMU type:enhanced

  • ZONE: the zone in which to create the VM.

REST

To create a VM that has the PMU enabled, make aPOST request to theinstances.insert method.In the request body, include theperformanceMonitoringUnit field:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances{  "name": "VM_NAME",  "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",  "disks": [    {      "boot": true,      "initializeParams": {        "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"      }    }  ],  "networkInterfaces": [    {      "network": "global/networks/default"    }  ],  "advancedMachineFeatures": {    "performanceMonitoringUnit": "PMU_TYPE"  }}

Replace the following:

  • PROJECT_ID: the ID of the project in which to createthe VM.

  • ZONE: the zone in which to create the VM.

  • VM_NAME: the name of the VM.

  • MACHINE_TYPE: aC4A orC4 machine type.If you try to enable PMU on a VM that doesn't use asupported machine type,then the VM creation operation fails.

  • IMAGE_PROJECT: the image project that contains theimage—for example,debian-cloud. For more information about thesupported image projects, seePublic images.

  • IMAGE: specify one of the following:

    • A specific version of the OS image—for example,debian-12-bookworm-v20240617.

    • Animage family, which must beformatted asfamily/IMAGE_FAMILY. This specifiesthe most recent, non-deprecated OS image. For example, if youspecifyfamily/debian-12, the latest version in the Debian 12image family is used. For more information about using imagefamilies, seeImage families best practices.

  • PMU_TYPE: the type of PMU to enable in the VM.Specify one of the following values:

    • Architectural PMU type:ARCHITECTURAL

    • Standard PMU type:STANDARD

    • Enhanced PMU type:ENHANCED

For more information about creating a VM, seeCreate and start a Compute Engine instance.

Enable the PMU while creating VMs in bulk

You can only create VMs in bulk that has the PMU enabled in zones that contain asupported CPU platform. For a list ofavailable CPUs by zone, seeAvailable regions and zones.

To create VMs in bulk that has the PMU enabled, select one of the followingoptions:

gcloud

To create VMs in bulk that has the PMU enabled, use thegcloud compute instances bulk create commandwith the--performance-monitoring-unit flag.

For example, to create VMs in bulk in a single zone and specify a namepattern, run the following command:

gcloud compute instances bulk create \    --count=COUNT \    --machine-type=MACHINE_TYPE \    --name-pattern="NAME_PATTERN" \    --performance-monitoring-unit=PMU_TYPE \    --zone=ZONE

Replace the following:

  • COUNT: the number of VMs to create.

  • MACHINE_TYPE: aC4A orC4 machine type.If you try to enable PMU on a VM that doesn't use asupported machine type,then the VM creation operation fails.

  • NAME_PATTERN: the name pattern for the VMs. Toreplace a sequence of numbers in a VM name, use a sequence of hash (#)characters. For example, usingvm-# for the name pattern generates VMswith names starting withvm-1,vm-2, and continuing up to the numberof VMs specified byCOUNT.

  • PMU_TYPE: the type of PMU to enable in the VMs.Specify one of the following values:

    • Architectural PMU type:architectural

    • Standard PMU type:standard

    • Enhanced PMU type:enhanced

  • ZONE: the zone in which to create VMs in bulk.

REST

To create VMs in bulk that have the PMU enabled, make aPOST request totheinstances.bulkInsert method.In the request body, include theperformanceMonitoringUnit field.

For example, to create VMs in bulk in a single zone and specify a namepattern, make aPOST request as follows:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/bulkInsert{  "count":COUNT,  "namePattern": "NAME_PATTERN",  "instanceProperties": {    "machineType": "MACHINE_TYPE",    "disks": [      {        "boot": true,        "initializeParams": {          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"        }      }    ],    "networkInterfaces": [      {        "network": "global/networks/default"      }    ],    "advancedMachineFeatures": {      "performanceMonitoringUnit": "PMU_TYPE"    }  }}

Replace the following:

  • PROJECT_ID: the ID of the project in which to createVMs in bulk.

  • ZONE: the zone in which to create VMs in bulk.

  • COUNT: the number of VMs to create.

  • NAME_PATTERN: the name pattern for the VMs. Toreplace a sequence of numbers in a VM name, use a sequence of hash (#)characters. For example, usingvm-# for the name pattern generates VMswith names starting withvm-1,vm-2, and continuing up to the numberof VMs specified byCOUNT.

  • MACHINE_TYPE: aC4A orC4 machine type.If you try to enable PMU on a VM that doesn't use asupported machine type,then the VM creation operation fails.

  • IMAGE_PROJECT: the image project that contains theimage—for example,debian-cloud. For more information about thesupported image projects, seePublic images.

  • IMAGE: specify one of the following:

    • A specific version of the OS image—for example,debian-12-bookworm-v20240617.

    • Animage family, which must beformatted asfamily/IMAGE_FAMILY. This specifiesthe most recent, non-deprecated OS image. For example, if youspecifyfamily/debian-12, the latest version in the Debian 12image family is used. For more information about using imagefamilies, seeImage families best practices.

  • PMU_TYPE: the type of PMU to enable in the VMs.Specify one of the following values:

    • Architectural PMU type:ARCHITECTURAL

    • Standard PMU type:STANDARD

    • Enhanced PMU type:ENHANCED

For more information about creating VMs in bulk, seeCreate VMs in bulk.

Enable the PMU while creating an instance template

If you want to create a regional instance template that has the PMU enabled,then make sure that at least one zone within the selected region contains asupported CPU platform. For a list ofavailable CPUs by zone, seeAvailable regions and zones.

After creating an instance template that has the PMU enabled, you can use thetemplate to do the following:

To create an instance template that has the PMU enabled, select one of thefollowing options:

gcloud

To create an instance template that has the PMU enabled, use thegcloud compute instance-templates create commandwith the--performance-monitoring-unit flag. To create a regional instancetemplate, you must also include the--instance-template-region flag.

For example, to create a regional instance template that has the PMUenabled, run the following command:

gcloud compute instance-templates createINSTANCE_TEMPLATE_NAME \    --instance-template-region=REGION \    --machine-type=MACHINE_TYPE \    --performance-monitoring-unit=PMU_TYPE

Replace the following:

  • INSTANCE_TEMPLATE_NAME: the name of the instancetemplate.

  • REGION: the region in which to create the instancetemplate.

  • MACHINE_TYPE: aC4A orC4 machine type.If you want to enable the Enhanced PMU type, then you must specify a C4machine type with 144 or 288 vCPUs. Otherwise, creating the instancetemplate fails.

  • PMU_TYPE: the type of PMU to include in the instancetemplate. Specify one of the following values:

    • Architectural PMU type:architectural

    • Standard PMU type:standard

    • Enhanced PMU type:enhanced

REST

To create an instance template that has the PMU enabled, make aPOSTrequest to one of the following methods:

In the request body, include theperformanceMonitoringUnit field.

For example, to create a regional instance template that has the PMUenabled, make aPOST request as follows:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceTemplates{  "name": "INSTANCE_TEMPLATE_NAME",  "properties": {    "disks": [      {        "boot": true,        "initializeParams": {          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"        }      }    ],    "machineType": "MACHINE_TYPE",    "networkInterfaces": [      {        "network": "global/networks/default"      }    ],    "advancedMachineFeatures": {      "performanceMonitoringUnit": "PMU_TYPE"    }  }}

Replace the following:

  • PROJECT_ID: the ID of the project in which to createthe instance template.

  • REGION: the region in which to create the instancetemplate.

  • INSTANCE_TEMPLATE_NAME: the name of the instancetemplate.

  • IMAGE_PROJECT: the image project that contains theimage—for example,debian-cloud. For more information about thesupported image projects, seePublic images.

  • IMAGE: specify one of the following:

    • A specific version of the OS image—for example,debian-12-bookworm-v20240617.

    • Animage family, which must beformatted asfamily/IMAGE_FAMILY. This specifiesthe most recent, non-deprecated OS image. For example, if youspecifyfamily/debian-12, the latest version in the Debian 12image family is used. For more information about using imagefamilies, seeImage families best practices.

  • MACHINE_TYPE: aC4A orC4 machine type.If you want to enable the Enhanced PMU type, then you must specify a C4machine type with 144 or 288 vCPUs. Otherwise, creating the instancetemplate fails.

  • PMU_TYPE: the type of PMU to include in the instancetemplate. Specify one of the following values:

    • Architectural PMU type:ARCHITECTURAL

    • Standard PMU type:STANDARD

    • Enhanced PMU type:ENHANCED

For more information about creating an instance template, seeCreate instance templates.

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.