This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

You can install and manage the Ops Agent on a fleet of Compute Engine VMsglobally or within a specific zone by usingVM Extension Manager policies.For example, you can use these policies to perform tasks like the following:

• Fleetwide installation: Install the Ops Agent on the following:

  • All VMs in one or more zones in your Google Cloud project.
  • All VMs globally (in your Google Cloud project).
  • A subset of VMs in a zone, identified by labels.
  • A subset of VMs across zones in your Google Cloud project, identifiedby labels.

• Version control:

  • Keep the Ops Agent updated to the latest version.
  • Pin the Ops Agent version to a specific release.

• Configuration management: Apply a custom configuration to the Ops Agenton all VMs managed by a policy.

With VM Extension Manager, you create policies that declare whichextensions you want to install on VMs. The Ops Agent is one of the availableextensions. VM Extension Manager policies can manage theOps Agent version 2.58.0 or newer, when the Ops Agent hasbeen installed by using VM Extension Manager. These policiescan't manage versions of the Ops Agent earlier than version2.58.0, Ops Agent instances installed by using other means,or any version of the legacyMonitoring agent orLogging agent.

You can create and manage zonal VM extension policies by using theGoogle Cloud console or the Google Cloud CLI, gcloud. You cancreate and manage global VM extension policies by using gcloud.

Before you begin

Before starting to using VM Extension Manager extensionpolicies, do the following:

• Review supported operating systems to verify thatboth the Ops Agent and VM Extension Manager are supportedon your operating systems.
• Grant the roles required to useVM Extension Manager.
• If you want to use a command-line interface to create and manageextension policies, theninstall the Google Cloud CLI.
• Uninstall any observability agents already installedon your VMs.

Review supported operating systems

Before attempting to use VM Extension Manager policies tomanage the Ops Agent, verify that your target operating system is compatiblewith both the Ops Agent and VM Extension Manager.

VM Extension Manager supports all operating systems supportedby the Ops Agent, except for SUSE Linux Enterprise Server (SLES) and Ubuntu.For more information about the operating systems supported by the Ops Agent,seeOperating systems.

If your operating system is supported by both the Ops Agent andVM Extension Manager, then follow the rest of this document.

Enable the APIs required to use the Ops Agent

To use the Ops Agent to write logs and metrics, you must enable theCloud Logging API and Cloud Monitoring API on your Google Cloud project.

Enable the APIs

Grant roles required to use the Ops Agent

To get the permissions that you need to use the Ops Agent to write logs and metrics, ask your administrator to grant you the following IAM roles on your service account:

• To write logs:Logging Logs Writer (roles/logging.logWriter)
• To write metrics:Monitoring Metric Writer (roles/monitoring.metricWriter)

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

For more information about roles and the Ops Agent, seeAuthorize the Ops Agent.

Grant roles required to use VM Extension Manager

To get the permissions that you need to create, view, modify, and delete VM extension policies, ask your administrator to grant you the following IAM roles on the project:

• To create extension policies:VM Extension Policy Admin (roles/compute.vmExtensionPolicyAdmin)
• To view extension policies:
  • VM Extension Policy Viewer (roles/compute.vmExtensionPolicyViewer)
  • VM Extension Policy Admin (roles/compute.vmExtensionPolicyAdmin)
• To modify extension policies:VM Extension Policy Admin (roles/compute.vmExtensionPolicyAdmin)
• To delete extension policies:VM Extension Policy Admin (roles/compute.vmExtensionPolicyAdmin)

For more information about granting roles, seeManage access to projects, folders, and organizations.

These predefined roles contain the permissions required to create, view, modify, and delete VM extension policies. To see the exact permissions that are required, expand theRequired permissions section:

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

For more information about IAM roles and permissions inCompute Engine, seeCompute Engine roles and permissions.

Install the Google Cloud CLI

You can create and manage VM extension policies by using the Google Cloud consoleor the Google Cloud CLI, gcloud. To use gcloud,you must first install it by performing the following steps:

1. If you haven't done so already, install theGoogle Cloud CLI.

   The extension policies described in this document use thebeta commandgroup.

1. If you haven't done so already, install thebeta component of thegcloud CLI by running the following command:

   gcloud components install beta

   To check if you have thebeta component installed, runthe following command:

   gcloud components list

   If you previously installed thebeta component, verify thathave the latest version:

   gcloud components update

Uninstall any observability agents

Before creating a VM Extension Manager policy to managethe Ops Agent on a VM, ensure that there are no instances of the Ops Agentor the legacy Monitoring agent and Logging agent already on the VM. Running theOps Agent and the legacy agents on the same VM can cause ingestion ofduplicate logs or conflicts in metrics ingestion.

If you use an extension policy to install the Ops Agent on a VM where anotherobservability agent is already installed, then the policy installs the agent, but theagent fails to run because a conflict is detected.

How you remove existing agents depends on how those agents were installed.

• Agents installed by a VM Manager OS Config policy, which includesthe following:

  • Ops Agent installed by using theGoogle Cloud console during VM creation.
  • Ops Agent installed by a GAVM Manager OS Config policy.
  • Ops Agent, or legacy Monitoring agent or Logging agent installed by a betaVM Manager OS Config policy.

  For information about identifying VMs using these policies, seeFind VMs covered by Ops Agent OS policies.

  For information about uninstalling the agent and removing theOS Config policies, seeUninstall the Ops Agent on VMs covered by Ops AgentOS policies.

• Agents installed manually by using an installation script. For informationabout uninstalling the agents, see the following:

  • Ops Agent:Uninstall the agent.
  • Legacy Monitoring agent:Uninstall the agent.
  • Legacy Logging agent:Uninstall the agent.

Install the Ops Agent by creating VM extension policies

Create VM extension policies to automatically install and manage theOps Agent on a fleet of Compute Engine virtual machines (VMs). By defininga policy, you can ensure that specific extensions, like the Ops Agent, areinstalled and maintained on any VMs that match criteria you specify, such asVM labels.

Policy conflicts and priorities

VM Extension Manager associates a priorty with each new policy,with lower numbers indicating higher priorities; the default priority is1000. A VM can be covered bymultiple policies for an extension like the Ops Agent, but only one policyfor the Ops Agent extension is effective on the VM.

VM Extension Manager uses priorities to resolveconflicts among policies applied to a VM. For more information about theresolution process, seePolicy priority and conflictresolution.

Policy rollout plans for global policies

VM Extension Manager global policies use a rollout plan todetermine how a policy is distributed to target VMs. There are two types ofrollout plans:

• Predefined rollout plans. There are two predefined rollout plans,chosen by the value used with the--rollout-predefined-planoption for gcloud CLI commands.

  • Slow rollout, which deploys the Ops Agent gradually across differentzones over a period of time.This rollout plan is recommended.

    Specify this rollout plan by using the--rollout-predefined-plan=slow_rollout option.

  • Fast rollout, which deploys the Ops Agent to all targeted VMs across allzones and regions immediately.

    Specify this rollout plan by using the--rollout-predefined-plan=fast_rolloutoption.

• Custom rollout plans, specified by using the--rollout-custom-planoption for gcloud CLI commands.

  Create custom rollout plans by adding them to the set of rollout plansin your Google Cloud project; for more information, see theCompute Engine API methodrolloutPlans.insert.

For more information about rollout plans, seeRollout plans for global policies.

Install the latest Ops Agent on all VMs

To create a policy that installs the latest version of the Ops Agent onall VMs in a zone or globally, and updates the Ops Agent when a new versionis released, do the following:

gcloud beta compute zone-vm-extension-policiescreatePOLICY_NAME \  --project=PROJECT_ID \  --zone=ZONE \--extensions=ops-agent

gcloud beta compute global-vm-extension-policiescreatePOLICY_NAME \  --project=PROJECT_ID \--extensions=ops-agent  \--rollout-predefined-plan=slow_rollout

Pin the Ops Agent to a specific version on all VMs

To create a policy that installs a specific version of the Ops Agent onall VMs in a zone or globally, do the following:

gcloud beta compute zone-vm-extension-policiescreatePOLICY_NAME \  --project=PROJECT_ID \  --zone=ZONE \--extensions=ops-agent  \  --version=ops-agent=VERSION

gcloud beta compute global-vm-extension-policiescreatePOLICY_NAME \  --project=PROJECT_ID \--extensions=ops-agent  \--rollout-predefined-plan=slow_rollout \  --version=ops-agent=VERSION

For a list of Ops Agent versions, see the Ops Agentreleases page on GitHub.

Install the Ops Agent on VMs that have a specific label

To create a policy that installs the latest version of Ops Agent on the VMsin a zone or globally that have a specific label, do the following:

gcloud beta compute zone-vm-extension-policiescreatePOLICY_NAME \  --project=PROJECT_ID \  --zone=ZONE \--extensions=ops-agent   --inclusion-labels=KEY1=VALUE1,KEY2=VALUE2

gcloud beta compute global-vm-extension-policiescreatePOLICY_NAME \  --project=PROJECT_ID \--extensions=ops-agent  \--rollout-predefined-plan=slow_rollout \  --inclusion-labels=KEY1=VALUE1,KEY2=VALUE2

Install the Ops Agent with a custom configuration on all VMs

To create a policy that installs the latest version of the Ops Agent onall VMs in a zone or globally, and provides custom configuration for theOps Agent, do the following:

gcloud beta compute zone-vm-extension-policiescreatePOLICY_NAME \  --project=PROJECT_ID \  --zone=ZONE \--extensions=ops-agent   --config-from-file=ops-agent="OPS_AGENT_CONFIG_PATH"

gcloud beta compute global-vm-extension-policiescreatePOLICY_NAME \  --project=PROJECT_ID \--extensions=ops-agent  \--rollout-predefined-plan=slow_rollout \  --config-from-file=ops-agent="OPS_AGENT_CONFIG_PATH"

If you provide a custom configuration for the Ops Agent when creatingor updating an extension policy, then the policy deploys the Ops Agent withthe custom configuration. You don't need to manually restart the agent.

The configuration is stored with the extension policy, so don't includesensitive data like passwords in the configuration. Because the configurationis stored with the extension policy, modifying the configuration file doesnot change the configuration of the agent. You must update the configurationstored with the policy by using the appropriategcloud command:

• For zonal policies, use thegcloud beta compute zone-vm-extension-policiesupdate command.
• For global policies, use thegcloud beta compute global-vm-extension-policiesupdate command.

When you provide a custom configuration for the Ops Agent,VM Extension Manager copies the configuration to the locationused by the Ops Agent foruser-specified configurationfiles on the target VM:

• Linux:/etc/google-cloud-ops-agent/config.yaml
• Windows:C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

If there is aconfig.yaml file present on the VM, the extension policyoverwrites it.

For general information about using theGoogle Cloud console and the gcloud CLI to create VM extensionpolicies, seeInstall VM extensions by creating extension policies .

Install the Ops Agent with a fast rollout plan at higher priority (global only)

To create a global policy that installs the latest version of the Ops Agenton by using a higher-than-default priority and thefast-rollout plan, use the followinggcloud beta compute global-vm-extension-policiescreate command:

gcloud beta compute global-vm-extension-policiescreatePOLICY_NAME \  --project=PROJECT_ID \--extensions=ops-agent  \  --rollout-predefined-plan=fast_rollout \  --priority=500

Replace the following variables in the command:

• POLICY_NAME: A name for the VM extension policy.
• PROJECT_ID: The identifier of the project.

Install the Ops Agent on a subset of zones in a Google Cloud project (global only)

To create a global policy that applies to only a subset of zones in aGoogle Cloud project, you must use a custom rollout plan that specifies thezones in which to apply the policy. For information about creatingcustom rollout plans, seeAbout rollout plans.To specify a set of zones, use thelocationSelector.includedLocations fieldwhen creating the rollout plan.

To create an extension policy that uses a custom rollout plan, usethe followinggcloud beta compute global-vm-extension-policiescreate command:

gcloud beta compute global-vm-extension-policiescreatePOLICY_NAME \  --project=PROJECT_ID \--extensions=ops-agent  \  --rollout-custom-plan=projects/PROJECT_ID/locations/global/rolloutPlans/CUSTOM_PLAN_NAME

Replace the following variables in the command:

• POLICY_NAME: A name for the VM extension policy.
• PROJECT_ID: The identifier of the project.

• CUSTOM_PLAN_NAME: The name associated with your customrollout plan.

Manage the Ops Agent by updating VM extension policies

To change how a policy manages the Ops Agent, update the policy.When you update a policy, VM Extension Manager rolls out the changes toall applicable VMs, typically within one minute. If you modify inclusion labels,then the Ops Agent might be installed on new VMs or uninstalled from existingVMs based on whether the VMs match the updated labels.

The following sections show how to manage the Ops Agent to do the following:

• Update the pinned version of the agent on all VMs
• Modify the configuration of the Ops Agent on all VMs

Update the pinned version of the Ops Agent on all VMs in a zone

To change the pinned version of the Ops Agent on all VMs in a zone,do the following:

gcloud beta compute zone-vm-extension-policiesupdatePOLICY_NAME \  --project=PROJECT_ID \  --zone=ZONE \--extensions=ops-agent   --version=ops-agent=VERSION

gcloud beta compute global-vm-extension-policiesupdatePOLICY_NAME \  --project=PROJECT_ID \--extensions=ops-agent  \--rollout-predefined-plan=slow_rollout \  --version=ops-agent=VERSION

Modify the configuration of the Ops Agent on all VMs

To modify the configuration of the Ops Agent, do thefollowing:

gcloud beta compute zone-vm-extension-policiesupdatePOLICY_NAME \  --project=PROJECT_ID \  --zone=ZONE \--extensions=ops-agent   --config-from-file=ops-agent="OPS_AGENT_CONFIG_PATH"

gcloud beta compute global-vm-extension-policiesupdatePOLICY_NAME \  --project=PROJECT_ID \--extensions=ops-agent  \--rollout-predefined-plan=slow_rollout \  --config-from-file=ops-agent="OPS_AGENT_CONFIG_PATH"

If you provide a custom configuration for the Ops Agent when creatingor updating an extension policy, then the policy deploys the Ops Agent withthe custom configuration. You don't need to manually restart the agent.

The configuration is stored with the extension policy, so don't includesensitive data like passwords in the configuration. Because the configurationis stored with the extension policy, modifying the configuration file doesnot change the configuration of the agent. You must update the configurationstored with the policy by using the appropriategcloud command:

• For zonal policies, use thegcloud beta compute zone-vm-extension-policiesupdate command.
• For global policies, use thegcloud beta compute global-vm-extension-policiesupdate command.

When you provide a custom configuration for the Ops Agent,VM Extension Manager copies the configuration to the locationused by the Ops Agent foruser-specified configurationfiles on the target VM:

• Linux:/etc/google-cloud-ops-agent/config.yaml
• Windows:C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

If there is aconfig.yaml file present on the VM, the extension policyoverwrites it.

For general information about using theGoogle Cloud console and the gcloud CLI to manage VM extensionpolicies, seeModifyextensions by updating a VM extension policy.

Extend an existing global policy to include new zones (global only)

When VMs are created in new zones after a global policy has been created androlled out, VM Extension Manager does not automatically apply thepolicy to the VMs in the new zones. To include the VMs in new zones, youmust restart the global policy rollout.

To restart a global policy rollout, use thegcloud beta compute global-vm-extension-policiesupdate commandand supply the--rollout-retry-uuid=UUID option.

For example, suppose you created and rolled out a global policy by using thefollowing command:

gcloud beta compute global-vm-extension-policiescreatePOLICY_NAME \  --project=PROJECT_ID \--extensions=ops-agent  \  --version=ops-agent=2.61.0 \--rollout-predefined-plan=slow_rollout \  --config-from-file=ops-agent="/usr/ops-agent-config.yaml"

To extend the policy to VMs created in previously unused zones, restart therollout by using the following command:

gcloud beta compute global-vm-extension-policiesupdate test-policyPOLICY_NAME \  --project=PROJECT_ID \--extensions=ops-agent  \  --version=ops-agent=2.61.0 \--rollout-predefined-plan=slow_rollout \  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \  --rollout-retry-uuid=UUID

Replace the following variables in the command:

• POLICY_NAME: A name for the VM extension policy.
• PROJECT_ID: The identifier of the project.

• UUID: A universally unique identifier (UUID) that identifies theretry request. You can use any UUID generator to create one. For moreinformation, seeRetry a rollout.

Update a global policy to exclude a set of zones (global only)

To update the zones to which a global policy that excludes some zones in aGoogle Cloud project, you must use a new custom rollout plan that specifies thezones in which to apply the policy. For information about creatingcustom rollout plans, seeAbout rollout plans.To specify a set of zones, use thelocationSelector.includedLocations fieldwhen creating the rollout plan.

To update an extension policy that uses a custom rollout plan, usethe followinggcloud beta compute global-vm-extension-policiesupdate command:

gcloud beta compute global-vm-extension-policiesupdatePOLICY_NAME \  --project=PROJECT_ID \--extensions=ops-agent  \  --rollout-custom-plan=projects/PROJECT_ID/locations/global/rolloutPlans/NEW_CUSTOM_PLAN_NAME \  --rollout-retry-uuid=UUID

Replace the following variables in the command:

• POLICY_NAME: A name for the VM extension policy.
• PROJECT_ID: The identifier of the project.

• NEW_CUSTOM_PLAN_NAME: The name associated with yourupdated custom rollout plan.
• UUID: A universally unique identifier (UUID) that identifies theretry request. You can use any UUID generator to create one. For moreinformation, seeRetry a rollout.

Uninstall the Ops Agent by deleting VM extension policies

To uninstall the Ops Agent, delete the VM extension policy that managesthe agent. If another active, lower-priority policy applies to a VM andalso manages the Ops Agent, then the agent remains installedon that VM based on the lower-priority policy.

VM Extension Manager removes the Ops Agent from all accessible VMswithin one minute of policy deletion. If a VM is inaccessible, thenVM Extension Manager skips deletion of the agent.If the VM becomes available again, then VM Extension Managerremoves the agent at that time.

gcloud beta compute zone-vm-extension-policiesdeletePOLICY_NAME \  --project=PROJECT_ID \  --zone=ZONE

gcloud beta compute global-vm-extension-policiesdeletePOLICY_NAME \  --project=PROJECT_ID \--rollout-predefined-plan=slow_rollout

gcloud beta compute global-vm-extension-policiesdeletePOLICY_NAME \  --project=PROJECT_ID \  --rollout-predefined-plan=fast_rollout \--rollout-retry-uuid=UUID

Retrieve information about VM extension policies

You can retrieve the following information about existing VM extension policies:

• A list of all policies in your Google Cloud project.
• Configuration information about a specific policy.

gcloud beta compute zone-vm-extension-policieslist \  --project=PROJECT_ID \  --zone=ZONE \  --page-size=PAGE_SIZE_INTEGER

gcloud beta compute zone-vm-extension-policiesdescribePOLICY_NAME \  --project=PROJECT_ID \  --zone=ZONE

gcloud beta compute global-vm-extension-policieslist \  --project=PROJECT_ID \  --page-size=PAGE_SIZE_INTEGER

gcloud beta compute global-vm-extension-policiesdescribePOLICY_NAME \  --project=PROJECT_ID

For general information about using theGoogle Cloud console and the gcloud CLI to retrieve informationabout VM extension policies, seeView extension policies.

Verify the installation of the Ops Agent

This section describes how to do the following:

• Verify the status or version of an Ops Agent installation
• Verify that the Ops Agent is collecting telemetry

Verify the status or version of an Ops Agent installation

To determine the status or version of the Ops Agent, use one of the followingGoogle Cloud console pages:

When the Ops Agent has been installed on the VM and is collecting logs andmetrics, the agent's status is marked with a green checkmark next to theOps Agent label.

To determine the version of the installed agent, hover over theOps Agentlabel on the Compute Engine or Monitoring dashboard.

Verify that the Ops Agent is collecting telemetry

If the Ops Agent has been successfully installed and is running correctly,then it sends metrics to Cloud Monitoring and logs to Cloud Logging.

• For information about verifying collection of metrics, seeAgent is running, but data is notingested.
• For information about verifying collection of logs, seeVerify successfullog collection.

Restart an Ops Agent installed by an extension policy

When the Ops Agent is installed and managed byVM Extension Manager, the Ops Agent isn't managed by thesystem-management service of the operating system, that is,systemd on Linuxor the Windows Service Manager on Windows. Therefore, Linuxsystemctlcommands and Windows*-Service commands don't work with an Ops Agentinstalled by an extension policy.

To restart an Ops Agent that was installed by an extension policy, doone of the following:

• Recreate the policy.

  1. Delete the policy. Deleting the policy stops anduninstalls the Ops Agent.

  2. Create a new policy. The new policy installs theOps Agent and starts it.

• Use a temporary, higher-priority policy. If the original policyaffects a large number of VMs but you only want to restart the Ops Agenton a small number, add a label to those VMs and configure the newpolicy to filter on the label.

  For example, if a policy with priority 1000failed to start the Ops Agent on a VM, you could add a label likestatus=failed to the VM. Thencreate a new policywith a higher priority, like 500. For example, a Google Cloud CLIcommand might look like the following:

  Zonal

  gcloud beta compute zone-vm-extension-policiescreatePOLICY_NAME \  --project=PROJECT_ID \  --zone=ZONE \--extensions=ops-agent  \  --inclusion-labels=status=failed \  --priority=500 \  --config-from-file=ops-agent=/usr/ops-agent-config.yaml

  Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.
  • ZONE: The target zone; for example,us-central1-f.

  Global

  gcloud beta compute global-vm-extension-policiescreatePOLICY_NAME \  --project=PROJECT_ID \--extensions=ops-agent  \  --inclusion-labels=status=failed \  --priority=500 \  --config-from-file=ops-agent=/usr/ops-agent-config.yaml \  --rollout-predefined-plan=fast_rollout

  Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.

  After the new policy successfully installs the Ops Agent, deletethe policy and remove the label from the VMs. The Ops Agent remainsinstalled on the VM because the original policy is still active.

Enable guest agent debug log on the VM

VM Extension Manager policies use theCompute Engine guest agent tomanage the Ops Agent as a VM extension.For information about enabling debug logging for the guest agent, seeView debug logs for the guest agent.

Troubleshoot extension policies

This section provides information about troubleshooting the use ofextension policies to manage the Ops Agent:

• gcloud beta compute zone-vm-extension-policies commands fail
• The extension policy is created, but the Ops Agent status is "not detected"
• Linuxsystemctl and Windows Service Manager don't work with the Ops Agent

For information about troubleshooting the Ops Agent, seeTroubleshoot the Ops Agent.

gcloud beta compute zone-vm-extension-policies commands fail

When agcloud beta compute zone-vm-extension-policies command fails, the response includestroubleshooting suggestions. Correct any errors in the commandflags or arguments suggested by the error message.

If the output of the command mentions insufficient IAMpermissions, then review the necessary roles and permissions described inGrant the roles required to use VM Extension Manager.

The extension policy is created, but the Ops Agent status is "not detected"

You successfully created an extension policy, but the Ops Agent shows a"not detected"status on the VM.

The Ops Agent might show as "not detected" if either of the following occurs:

• The extension policy fails to install the Ops Agent.
• An installed Ops Agent encounters an error condition that prevents it fromrunning.

The following sections describe how to diagnose these cases.

Verify that the Ops Agent was installed by the policy

VM Extension Manager policies use theCompute Engine guest agent tomanage the Ops Agent as a VM extension.

To determine if the Ops Agent was installed by the extension policy, useone of the following to look for log entries from the guest agent:

If you see logs containing a string likeFailed to install plugin"ops-agent-plugin" ..., or the query returns no logs, then theextension policy failed to install the Ops Agent. For next steps, seeExtension policy fails to install the Ops Agent.

If you see logs containing a string likeSuccessfully installed plugin"ops-agent_nnnnnnnn", then the extension policy successfully installed theOps Agent. For next steps, seeInstalled Ops Agent is "not detected".

Extension policy fails to install the Ops Agent

An extension policy might be ineffective if one of the following is true:

• The guest agent is not installed on the VM. To diagnose and fix this condition,do the following:

  1. Verify that the VM is using one of theoperating systemssupported for the Compute Engine guest environment.

  2. View the packages installed on theVMto verify thatgoogle-guest-agent is included.

  3. If thegoogle-guest-agent is not installed,theninstall the guest agent.

• The guest agent is installed but outdated. To diagnose and fix this condition,do the following:

  1. Validate the guest environmentto determine the version of thegoogle-guest-agent package.VM Extension Manager requires version20241209.01or newer.

  2. If the version of thegoogle-guest-agent is older than20241209.01,thenupdate theguest environment.

• The VM's operating system is not supported byVM Extension Manager. For moreinformation, seeReview supported operating systems.

Installed Ops Agent has status "not detected"

The Ops Agent can have a status of "not detected" if one of the followingis true:

• There are observability agents installed on the VM already. Existingagents can cause conflicts and must be uninstalled. For more information,seeUninstall any observability agents.

  After uninstalling any previously installed agents, you canrestart the Ops Agent.

• The Ops Agent has insufficient permissions to send data toCloud Logging and Cloud Monitoring. For more information, seeCommon reasons for telemetry-transmission failures.

Verify that the Ops Agent configuration is valid

You provided a custom configuration to the Ops Agent by creating orupdating an extension policy, but the agent status is "not detected".The problem might be an error in your custom configuration. Use theguest agent debug logs to look for configuration errors.

Enable guest agent debug logging

For information about enabling debug logging for the guest agent, seeView debug logs for the guest agent.

Examine debug logs

If you see logs containing the stringThe agent config file is not valid,then the custom configuration for the Ops Agent you provided whencreating or updating the extension policy is invalid.

To fix this problem, do the following:

• Correct the configuration by referring toConfigure the Ops Agent.For information about the structure of an Ops Agent configuration file.

• Update the extension policy with the corrected configuration.

Linuxsystemctl status and WindowsGet-Service commands don't work with the Ops Agent

You run a command likesudo systemctl status google-cloud-ops-agent"*"but it returns no information.

When the Ops Agent is installed and managed byVM Extension Manager, the Ops Agent isn't managed by thesystem-management service of the operating system, that is,systemd on Linuxor the Windows Service Manager on Windows.

To find the status information for an Ops Agent managed byVM Extension Manager, see the following:

• Agent health checks
• Agent self logs.

Linuxsystemctl restart and WindowsRestart-Service commands don't work with the Ops Agent

You run a command likesudo systemctl restart google-cloud-ops-agentbut the Ops Agent isn't restarted.

When the Ops Agent is installed and managed byVM Extension Manager, the Ops Agent isn't managed by thesystem-management service of the operating system, that is,systemd on Linuxor the Windows Service Manager on Windows. Therefore, you can't stop or start the Ops Agent manually,and commands like the following don't work with the Ops Agent:

• Linux:sudo systemctl [stop|start|restart]
• Windows:Stop-Service,Start-Service,Restart-Service

To stop or restart an Ops Agent managed by VM Extension Manager,you must uninstall the agent by deleting the extension policy. For moreinformation about stopping or restarting the Ops Agent, seeRestart an Ops Agent installed by an extension policy.

Additional troubleshooting information

For more information about troubleshooting the creation and use ofVM Extension Manager policies, seeTroubleshootVM extensions.

For more information about troubleshooting the Ops Agent, seeTroubleshoot the Ops Agent.

Quota

For information about the number of extension policies you can createin a Google Cloud project, seeQuota.

Pricing

For information about costs associated with usingVM Extension Manager, seePricing.

If you install the Ops Agent, then you might be charged for the metrics,logs, or traces that the agent sends to your Google Cloud project. For pricinginformation, seeGoogle Cloud Observability pricing.

What's next

• View detailed information aboutconfiguring the Ops Agent.
• Learn more aboutVM Extension Manager.