Console
    Start free

    Manage the PMU in Compute Engine instances

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

    • Change the PMU type enabled in the compute instance. This change is useful when you want to track different types of low-level CPU events.

    • Disable the PMU in the compute instance. This action is useful when you no longer need to access the performance counters in the PMU.

    This document explains how to change the performance monitoring unit (PMU) type that is enabled in a Compute Engine instance, or disable it. To learn more about the PMU, see PMU overview .

    Before you begin

    • If you haven't already, set up authentication . Authentication verifies your identity 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. After installation, initialize the Google Cloud CLI by running the following command:

        gcloud  
init

        If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

      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.

        Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:

        gcloud  
init

        If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

      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 compute instance 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 compute instance or disable it. To see the exact permissions that are required, expand the Required permissionssection:

    Required permissions

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

    • To update a compute instance: compute.instances.update on the compute instance

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

    Change the PMU type in a compute instance

    Before you change the PMU type for an existing A4X, C4A, C4, or M4 instance, view the details of the compute instance by using the Google Cloud CLI or REST API. In the output from the command or API request, verify the following:

    1. To verify that the PMU type is enabled in the compute instance, check the value of the performanceMonitoringUnit field. If the field is missing, then the PMU is disabled.

    2. If you want to enable the enhanced PMU type, then you must verify that the compute instance uses one of the following machine types by checking the value of the machineType field:

      • A C4 machine type with 144 or 288 vCPUs

      • One of the following M4 machine types:

        • m4-megamem-112

        • m4-megamem-224

        • m4-ultramem-56

        • m4-ultramem-112

        • m4-ultramem-224

      If your compute instance uses a different machine type, then you must change the machine type that the compute instance uses before you can monitor enhanced PMU types.

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

    To change the PMU type enabled in an existing compute instance, select one of the following options:

    gcloud

    1. Create an empty YAML file.

    2. To export the properties of a compute instance into the YAML file that you've just created, use the gcloud compute instances export command :

       gcloud compute instances export INSTANCE_NAME 
\
    --destination= YAML_FILE 
\
    --zone= ZONE

      Replace the following:

      • INSTANCE_NAME : the name of the compute instance.

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

      • ZONE : the zone where the compute instance exists.

    3. 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

    4. To update the compute instance 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 INSTANCE_NAME 
\
    --most-disruptive-allowed-action=RESTART \
    --source= YAML_FILE 
\
    --zone= ZONE

      Replace the following:

      • INSTANCE_NAME : the name of the compute instance.

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

      • ZONE : the zone where the compute instance exists.

    REST

    1. To view the properties of an existing compute instance, make a GET request to the instances.get method :

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

      Replace the following:

      • PROJECT_ID : the ID of the project where the compute instance is located.

      • ZONE : the zone where the compute instance exists.

      • INSTANCE_NAME : the name of an existing compute instance.

    2. To update the compute instance and restart it, make a PUT request to the instances.update method as follows:

      • In the request URL, include the mostDisruptiveAllowedAction query parameter set to RESTART .

      • For the request body, use the GET request output from the previous step. However, in the advancedMachineFeatures field, you must change the value of the performanceMonitoringUnit field to your chosen PMU type.

      The PUT request is similar to the following:

       PUT https://compute.googleapis.com/compute/v1/projects/ PROJECT_ID 
/zones/ ZONE 
/instances/ INSTANCE_NAME 
?mostDisruptiveAllowedAction=RESTART

{
  "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

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

    Disable the PMU in a compute instance

    You can disable the PMU in a compute instance without stopping the compute instance. However, to make the change effective, you must restart the compute instance as described in this section.

    To disable the PMU in an existing compute instance, select one of the following options:

    gcloud

    1. Create an empty YAML file.

    2. To export the properties of a compute instance into the YAML file that you've just created, use the gcloud compute instances export command :

       gcloud compute instances export INSTANCE_NAME 
\
    --destination= YAML_FILE 
\
    --zone= ZONE

      Replace the following:

      • INSTANCE_NAME : the name of the compute instance.

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

      • ZONE : the zone where the compute instance exists.

    3. In the YAML configuration file, remove the performanceMonitoringUnit field. If the advancedMachineFeatures field is empty, then remove it as well.

       advancedMachineFeatures:
  performanceMonitoringUnit: PMU_TYPE

    4. To update the compute instance 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 INSTANCE_NAME 
\
    --most-disruptive-allowed-action=RESTART \
    --source= YAML_FILE 
\
    --zone= ZONE

      Replace the following:

      • INSTANCE_NAME : the name of the compute instance.

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

      • ZONE : the zone where the compute instance exists.

    REST

    1. To view the properties of an existing compute instance, make a GET request to the instances.get method :

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

      Replace the following:

      • PROJECT_ID : the ID of the project where the compute instance exists.

      • ZONE : the zone where the compute instance exists.

      • INSTANCE_NAME : the name of an existing compute instance.

    2. To update the compute instance and restart it, make a PUT request to the instances.update method . In the request, do the following:

      • In the request URL, include the mostDisruptiveAllowedAction query parameter set to RESTART .

      • For the request body, use the GET request output from the previous step. However, you must remove the performanceMonitoringUnit field and, if there aren't other fields in the advancedMachineFeatures field, the advancedMachineFeatures field too.

      The PUT request is similar to the following:

       PUT https://compute.googleapis.com/compute/v1/projects/ PROJECT_ID 
/zones/ ZONE 
/instances/ INSTANCE_NAME 
?mostDisruptiveAllowedAction=RESTART

{
  ~"advancedMachineFeatures": {
    ...
  }~,
  ...
}

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

    What's next
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: