Manage the PMU in VMs

This document describes how to change the performance monitoring unit (PMU) type enabled in a virtual machine (VM) instance, or disable the PMU in a VM.

After you've enabled the PMU in a VM and run performance-monitoring software on the VM, you can do the following:

Change the PMU type enabled in the VM. This is useful when you want to track different types of low-level CPU events.
Disable the PMU in the VM. Disabling the PMU in a VM is useful when you no longer need to access the PMU's performance counters.

Before you begin

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 change the PMU type enabled in a VM or disable it, 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 change the PMU type enabled in a VM or disable it. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to change the PMU type enabled in a VM or disable it:

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.

Change the PMU type in a VM

Before changing the PMU type enabled in an existing VM, view the details of the VM using the Google Cloud CLI or REST. In the output from the command or API request, verify the following:

To verify the PMU type enabled in the VM, check the value of the performanceMonitoringUnit field.
If you want to enable the Enhanced PMU type, then make sure that the VM is using a C4 machine type with 96 or 192 vCPUs by checking the value of the machineType field. If not, then change the machine type of the VM.

You don't have to stop the VM to change the PMU type enabled in it. However, to make the change effective, you must restart the VM as described in this section.

To change the PMU type enabled 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, locate the performanceMonitoringUnit field and change its value to specify a different PMU type.
```
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. Locate the performanceMonitoringUnit field, and then change its value to specify a different PMU type.
```
"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.

Disable the PMU in a VM

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

To disable 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, locate the performanceMonitoringUnit field and set its value to NONE.
```
advancedMachineFeatures:
  performanceMonitoringUnit: NONE
```
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. Locate the performanceMonitoringUnit field, and then change its value to NONE.
```
"advancedMachineFeatures": {
  "performanceMonitoringUnit": "NONE"
}
```
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.

What's next

Learn how to set the number of threads per core.