Enable the PMU in VMs

This document describes how to enable the performance monitoring unit (PMU) in new or existing virtual machine (VM) instances.

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

Before you begin

If you haven't already, then see how the PMU works.
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:
gcloud
1. Install the Google Cloud CLI, then initialize it by running the following command:
```
gcloud init
```
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.
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.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

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 the Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on your project. For more information about granting roles, see Manage 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 the Required 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 a legacy 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 with custom roles or other predefined roles.

Enable the PMU in VMs

To enable the PMU in one or more C4 VMs, select one of the following methods:

Enable the PMU in an existing VM
Enable the PMU while creating a VM
Enable the PMU while creating VMs in bulk
Enable the PMU while creating an instance template

After you've enabled the PMU in one or more VMs, you can install and use performance-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 a supported machine type and CPU platform by doing the following:

To verify the machine type and CPU platform of the VM, view the details of the VM.
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 where the VM is located, see Available regions and zones.
  
  Note: If a supported CPU platform is not available in the zone of the VM, then you must migrate the VM to a different zone or create a new VM with the PMU enabled as described in this document.
2. Change the machine type as follows:
  - To enable the Enhanced PMU type, you must specify a C4 machine type with 96 or 192 vCPUs.
  - Otherwise, to enable the Architectural or Standard PMU type, specify any C4 machine type.

You don't have to stop the VM to enable the PMU. However, to make the change effective, 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

Create an empty YAML file.
To export the properties of a VM into the YAML file that you've just created, use the gcloud compute instances export command.
```
gcloud compute instances export VM_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 you created in the previous step.
- ZONE: the zone where the VM is located.
In the YAML configuration file, add the performanceMonitoringUnit field.
```
advancedMachineFeatures:
  performanceMonitoringUnit: PMU_TYPE
```
Replace PMU_TYPE with one of the following values:
- Architectural PMU type: ARCHITECTURAL
- Standard PMU type: STANDARD
- Enhanced PMU type: ENHANCED
To update the VM and restart it, use the gcloud compute instances update-from-file command with the --most-disruptive-allowed-action flag set to RESTART.
```
gcloud compute instances update-from-file VM_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 the configuration data that you modified in the previous step.
- ZONE: the zone where the VM is located.

REST

Create an empty JSON file.
To view the properties of an existing VM, make a GET request to the instances.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 is located.
- ZONE: the zone where the VM is located.
- VM_NAME: the name of an existing VM.
In the empty JSON file that you created in the previous steps, do the following:
1. Enter the VM properties from the GET request output.
2. Add the performanceMonitoringUnit field.
```
{
  "advancedMachineFeatures": {
    "performanceMonitoringUnit": "PMU_TYPE"
  },
  ...
}
```
  Replace PMU_TYPE with one of the following values:
  - Architectural PMU type: ARCHITECTURAL
  - Standard PMU type: STANDARD
  - Enhanced PMU type: ENHANCED
To update the VM and restart it, make a PUT request to the instances.update method. In the request, do the following:
- In the request URL, include the most_disruptive_allowed_action query parameter set to RESTART.
- For the request body, use the VM properties from the JSON file that you created and updated in the previous steps.
```
PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME?most_disruptive_allowed_action=RESTART

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

For more information about updating the properties of a VM, see Update VM properties.

Enable the PMU while creating a VM

You can only create a VM with the PMU enabled in a zone that contains a supported CPU platform. For a list of available CPUs by zone, see Available regions and zones.

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

gcloud

To create a VM with the PMU enabled, use the gcloud compute instances create command with the --performance-monitoring-unit flag.

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

Replace the following:

VM_NAME: the name of the VM.
MACHINE_TYPE: a C4 machine type. If you want to enable the Enhanced PMU type, then you must specify a C4 machine type with 96 or 192 vCPUs. Otherwise, creating the VM 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 with the PMU enabled, make a POST request to the instances.insert method. In the request body, include the performanceMonitoringUnit 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 create the VM.
ZONE: the zone in which to create the VM.
VM_NAME: the name of the VM.
MACHINE_TYPE: a C4 machine type. If you want to enable the Enhanced PMU type, then you must specify a C4 machine type with 96 or 192 vCPUs. Otherwise, creating the VM fails.
IMAGE_PROJECT: the image project that contains the image—for example, debian-cloud. For more information about the supported image projects, see Public images.
IMAGE: specify one of the following:
- A specific version of the OS image—for example, debian-12-bookworm-v20240617.
- An image family, which must be formatted as family/IMAGE_FAMILY. This specifies the most recent, non-deprecated OS image. For example, if you specify family/debian-12, the latest version in the Debian 12 image family is used. For more information about using image families, see Image 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, see Create and start a Compute Engine instance.

Enable the PMU while creating VMs in bulk

You can only create VMs in bulk with the PMU enabled in zones that contain a supported CPU platform. For a list of available CPUs by zone, see Available regions and zones.

To create VMs in bulk with the PMU enabled, select one of the following options:

gcloud

To create VMs in bulk with the PMU enabled, use the gcloud compute instances bulk create command with the --performance-monitoring-unit flag.

For example, to create VMs in bulk in a single zone and specify a name pattern, 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: a C4 machine type. If you want to enable the Enhanced PMU type, then you must specify a C4 machine type with 96 or 192 vCPUs. Otherwise, creating the VM fails.
NAME_PATTERN: the name pattern for the VMs. To replace a sequence of numbers in a VM name, use a sequence of hash (#) characters. For example, using vm-# for the name pattern generates VMs with names starting with vm-1, vm-2, and continuing up to the number of VMs specified by COUNT.
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 with the PMU enabled, make a POST request to the instances.bulkInsert method. In the request body, include the performanceMonitoringUnit field.

For example, to create VMs in bulk in a single zone and specify a name pattern, make a POST 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 create VMs 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. To replace a sequence of numbers in a VM name, use a sequence of hash (#) characters. For example, using vm-# for the name pattern generates VMs with names starting with vm-1, vm-2, and continuing up to the number of VMs specified by COUNT.
MACHINE_TYPE: a C4 machine type. If you want to enable the Enhanced PMU type, then you must specify a C4 machine type with 96 or 192 vCPUs. Otherwise, creating the VM fails.
IMAGE_PROJECT: the image project that contains the image—for example, debian-cloud. For more information about the supported image projects, see Public images.
IMAGE: specify one of the following:
- A specific version of the OS image—for example, debian-12-bookworm-v20240617.
- An image family, which must be formatted as family/IMAGE_FAMILY. This specifies the most recent, non-deprecated OS image. For example, if you specify family/debian-12, the latest version in the Debian 12 image family is used. For more information about using image families, see Image 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
ZONE: the zone in which to create VMs in bulk.

For more information about creating VMs in bulk, see Create VMs in bulk.

Enable the PMU while creating an instance template

If you want to create a regional instance template with the PMU enabled, then make sure that at least one zone within the selected region contains a supported CPU platform. For a list of available CPUs by zone, see Available regions and zones.

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

Enable the PMU in the VMs of a managed instance group (MIG) when you do the following:
- Create a MIG.
- Apply new VM configurations in a MIG.
Create a VM with the PMU enabled.

To create an instance template with the PMU enabled, select one of the following options:

gcloud

To create an instance template with the PMU enabled, use the gcloud compute instance-templates create command with the --performance-monitoring-unit flag.

For example, to create a global instance template with the PMU enabled, run the following command:

gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \
    --machine-type=MACHINE_TYPE \
    --performance-monitoring-unit=PMU_TYPE

Replace the following:

INSTANCE_TEMPLATE_NAME: the name of the instance template.
MACHINE_TYPE: a C4 machine type. If you want to enable the Enhanced PMU type, then you must specify a C4 machine type with 96 or 192 vCPUs. Otherwise, creating the VM fails.
PMU_TYPE: the type of PMU to include in the instance template. Specify one of the following values:
- Architectural PMU type: architectural
- Standard PMU type: standard
- Enhanced PMU type: enhanced

REST

To create an instance template with the PMU enabled, make a POST request to one of the following methods:

To create a global instance template: instanceTemplates.insert method.
To create a regional instance template: regionInstanceTemplates.insert method.

In the request body, include the performanceMonitoringUnit field.

For example, to create a global instance template with the PMU enabled, make a POST request as follows:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/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 create the instance template.
INSTANCE_TEMPLATE_NAME: the name of the instance template.
IMAGE_PROJECT: the image project that contains the image—for example, debian-cloud. For more information about the supported image projects, see Public images.
IMAGE: specify one of the following:
- A specific version of the OS image—for example, debian-12-bookworm-v20240617.
- An image family, which must be formatted as family/IMAGE_FAMILY. This specifies the most recent, non-deprecated OS image. For example, if you specify family/debian-12, the latest version in the Debian 12 image family is used. For more information about using image families, see Image families best practices.
MACHINE_TYPE: a C4 machine type. If you want to enable the Enhanced PMU type, then you must specify a C4 machine type with 96 or 192 vCPUs. Otherwise, creating the VM fails.
PMU_TYPE: the type of PMU to include in the instance template. 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, see Create instance templates.

What's next

Learn how to connect to a VM.
Learn how to change PMU type in a VM or disable the PMU.