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, 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 as follows.
Select the tab for how you plan to use the samples on this page:
gcloud
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- 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.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
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:
To verify that a supported CPU platform is available in the zone where the VM is located, see Available regions and zones.
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 toRESTART
.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 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 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:
Enter the VM properties from the
GET
request output.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 theinstances.update
method. In the request, do the following:In the request URL, include the
most_disruptive_allowed_action
query parameter set toRESTART
.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 specifyfamily/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, usingvm-#
for the name pattern generates VMs with names starting withvm-1
,vm-2
, and continuing up to the number of 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 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://www.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, usingvm-#
for the name pattern generates VMs with names starting withvm-1
,vm-2
, and continuing up to the number of VMs specified byCOUNT
.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 specifyfamily/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:
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 specifyfamily/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.