The Ops Agent collects logs and metrics on Compute Engine instances, sending your logs to Cloud Logging and your metrics to Cloud Monitoring.
Before you begin
To install the agent, ensure that you have the following:
A supported VM instance in a Google Cloud project.
Credentials on the VM instance that authorize communication with Cloud Logging and Cloud Monitoring. Compute Engine VM instances generally have the correct credentials by default. If you are running very old Compute Engine instances or if you created Compute Engine instances without the default credentials, then you might not have the proper credentials. You must complete the Authorize the Ops Agent procedures.
Ensure that you enable the services for both the Cloud Logging API and Cloud Monitoring API.
Ensure your VM doesn't have the legacy Cloud Logging agent or Cloud Monitoring agent installed on it. This can cause ingestion of duplicate logs or a conflict in metrics ingestion. In addition, this agent uses new configuration files that are not compatible with the old agents.
If you have the old agents installed, save the custom configuration files for the Cloud Monitoring agent and the custom configuration files for the Cloud Logging agent, and complete the uninstall steps for the Cloud Monitoring agent and the uninstall steps for the Cloud Logging agent.
For users with VMS that don't have access to remote package repositories, refer to the VMs without remote package access section for more information.
Installing the agent using the command line
To install the agent using the command line, use the following instructions.
Installing the latest version of the agent
To install the latest version of the agent, complete the following steps.
Linux
Open a terminal connection to your VM instance using SSH or a similar tool and ensure you have
sudo
access.Change to a directory you have write access to, for example your home directory.
Run:
curl -sSO https://dl.google.com/cloudagents/add-google-cloud-ops-agent-repo.sh sudo bash add-google-cloud-ops-agent-repo.sh --also-install
Windows
Connect to your instance using RDP or a similar tool and login to Windows.
Open a PowerShell terminal with administrator privileges by right-clicking the PowerShell icon and selecting Run as Administrator.
Run the following PowerShell commands:
(New-Object Net.WebClient).DownloadFile("https://dl.google.com/cloudagents/add-google-cloud-ops-agent-repo.ps1", "${env:UserProfile}\add-google-cloud-ops-agent-repo.ps1") Invoke-Expression "${env:UserProfile}\add-google-cloud-ops-agent-repo.ps1 -AlsoInstall"
Installing a specific version of the agent
To install a specific version of the agent, complete the following steps.
Linux
Open a terminal connection to your VM instance using SSH or a similar tool and ensure you have
sudo
access.Change to a directory you have write access to, for example your home directory.
Download the agent installation script:
curl -sSO https://dl.google.com/cloudagents/add-google-cloud-ops-agent-repo.sh
When running the
add-google-cloud-ops-agent-repo.sh
script, you can also set the following flags:--verbose
: Turns on verbose logging during the script execution.--also-install
: Installs the agent after adding the agent package repository.--version
: Sets the agent version for the script to install.--uninstall
: Uninstalls the agent.--remove-repo
: Removes the corresponding agent package repository after installing or uninstalling the agent.--dry-run
: Triggers only a dry run of the script execution and prints out the commands that it is supposed to execute.
--uninstall-standalone-logging-agent
: Uninstalls the legacy Logging agent (StackdriverLogging
).--uninstall-standalone-monitoring-agent
: Uninstalls the legacy Monitoring agent (StackdriverMonitoring
).
See the script comments for more information and example usage.
Add the agent's package repository and install the agent:
To list the available agent versions in order to select which version to install, refer to Listing all agent versions.
For production environments, you might want to pin to a major version to avoid installing major versions that might include backward incompatible changes. To pin to a major version, run:
sudo bash add-google-cloud-ops-agent-repo.sh --also-install \ --version=MAJOR_VERSION.*.*
For example, to pin to the 1.x.x of the agent, run:
sudo bash add-google-cloud-ops-agent-repo.sh --also-install \ --version=1.*.*
To install a specific version of the agent, run:
sudo bash add-google-cloud-ops-agent-repo.sh --also-install \ --version=MAJOR_VERSION.MINOR_VERSION.PATCH_VERSION
You can delete the installation script after it runs successfully.
To verify that the agent is working as expected, run:
sudo systemctl status google-cloud-ops-agent"*"
The status of the agent should be OK.
If you have trouble with the installation, refer to the Troubleshooting page.
Windows
Connect to your instance using RDP or a similar tool and login to Windows.
Open a PowerShell terminal with administrator privileges by right-clicking the PowerShell icon and selecting Run as Administrator.
Download the agent installation script:
(New-Object Net.WebClient).DownloadFile("https://dl.google.com/cloudagents/add-google-cloud-ops-agent-repo.ps1", "${env:UserProfile}\add-google-cloud-ops-agent-repo.ps1")
When running the
add-google-cloud-ops-agent-repo.ps1
script, you can also set the following flags:-Verbose
: Turns on verbose logging during the script execution.-AlsoInstall
: Installs the agent after adding the agent package repository.-Version
: Sets the agent version for the script to install.-Uninstall
: Uninstalls the agent.-RemoveRepo
: Removes the corresponding agent package repository after installing or uninstalling the agent.-WhatIf
: Triggers only a dry run of the script execution and prints out the commands that it is supposed to execute.-UninstallStandaloneLoggingAgent
: Uninstalls the legacy Logging agent (StackdriverLogging
).-UninstallStandaloneMonitoringAgent
: Uninstalls the legacy Monitoring agent (StackdriverMonitoring
).
See the script comments for more information and example usage.
Add the agent's package repository and install the agent:
To list the available agent versions in order to select which version to install, refer to Listing all agent versions.
For production environments, you might want to pin to a major version to avoid installing major versions that might include backward incompatible changes. To pin to a major version, run:
Invoke-Expression "${env:UserProfile}\add-google-cloud-ops-agent-repo.ps1 -AlsoInstall -Version MAJOR_VERSION.*.*"
For example, to pin to the 1.x.x of the agent, run:
Invoke-Expression "${env:UserProfile}\add-google-cloud-ops-agent-repo.ps1 -AlsoInstall -Version 1.*.*"
To install a specific version of the agent, run:
Invoke-Expression "${env:UserProfile}\add-google-cloud-ops-agent-repo.ps1 -AlsoInstall -Version version-number"
For example:
Invoke-Expression "${env:UserProfile}\add-google-cloud-ops-agent-repo.ps1 -AlsoInstall -Version 1.0.1"
You can delete the installation script after it runs successfully.
To verify that the agent is working as expected, run:
Get-Service google-cloud-ops-agent
The status of the agent should be
Running
.
If you have trouble with the installation, refer to the Troubleshooting page.
Installing the agent using the Google Cloud console
You can install the agent on an individual Linux VM by using the Google Cloud console from the Cloud Monitoring or Compute Engine pages.
Cloud Monitoring
In the Google Cloud console, select your Google Cloud project.
In the navigation pane, select Monitoring.
In the Monitoring navigation pane, select Dashboards.
In the table of dashboards, locate the VM Instances entry, and then click on the name.
The List view on the Inventory tab on the dashboard lists all VMs and includes a status column for your agent, as shown in the following screenshot:
The Agent column reports the following values:
Not detected: You don't have an agent installed. If Cloud Monitoring doesn't detect any agents installed on the Compute Engine instance, then you can install an agent by doing the following:
- Select the VM instances on which you want to install agents.
Click the Install/update agents option on the Instances table, which brings up an installation workflow in the dashboard, and follow the instructions.
You can also install or update agents from the VM Details page for a specific VM.
The Ops Agent collects both metrics and logs by default. You can change this default behavior by configuring the Ops Agent.
Ops Agent: You are running the Ops Agent. If you don't see a green checkmark beside the entry, then there is an agent upgrade available, based on the detected operating system of your VM.
When you hover over the Ops Agent indicator in the table, you see information about the version of the Ops Agent. If you are running an older version, you also see a recommendation to upgrade your agent.
Pending: The Ops Agent is being installed or upgraded.
Legacy Agent: You are running the legacy Monitoring or the Logging agent. See Migrating from the legacy agents to the Ops Agent for information on transitioning to the Ops Agent.
Not applicable: This VM is not a supported platform for running the agent.
Unknown: The VM is not running, so the agent's status is not known.
Compute Engine
Go to the VM instances page in the Google Cloud console.
Click the name of the VM that you want to install the agent on. The Details page opens.
Click the Observability tab. The Observability page opens.
Click Install Ops Agent.
Click Run in Cloud Shell. Cloud Shell opens and pastes the installation command.
Press Enter on your keyboard to run the command.
Click Authorize to allow Cloud Shell to install the agent. The installation is successful if you see a line in Cloud Shell that is similar to the following:
Instance: projects/example-project/zones/us-west1-a/instances/example-vm successfully runs ops-agent
Verify that the Ops Agent is running
There are two ways to verify that the Ops Agent is running correctly:
Check that all the [health checks][health-checks] passed.
Go to the pre-configured Monitoring VM Instances dashboard and check that the Agent column for this VM indicates the Ops Agent.
Optional tasks
This section describes how to perform common maintenance tasks.
Configuring an HTTP proxy
If you use an HTTP proxy for proxying requests to the Logging and Monitoring APIs, do the following:
Linux
Edit the following configuration file (create the file if it doesn't already exist):
/etc/systemd/system.conf
Add the following to the file:
DefaultEnvironment="HTTP_PROXY=http://proxy-ip:proxy-port" "HTTPS_PROXY=http://proxy-ip:proxy-port" "NO_PROXY=http://metadata.google.internal" # Skip proxy for the local Metadata Server.
Reload the environment variables:
sudo systemctl daemon-reload
Restart the agent by running the following command on your VM instance:
sudo systemctl restart google-cloud-ops-agent.target
Windows
If you use an HTTP proxy, run the following command from an administrator command prompt. This sets the
HTTP_PROXY
andHTTPS_PROXY
environment variables so that the agent can send data using outbound HTTPS:setx HTTP_PROXY http://proxy-ip:proxy-port /m setx HTTPS_PROXY http://proxy-ip:proxy-port /m setx no_proxy metadata.google.internal /m
Determining the agent version
To determine the version of the Ops Agent on your system, run the following commands on your VM instance:
Google Cloud console
To see the version of your Ops Agent on a VM:
Locate the entry for the VM in the Instances table in the Monitoring VM Instances page. For navigation information, see Installing the agent using the Google Cloud console.
Hover over the Ops Agent indicator in the table entry.
CENTOS / RHEL
Run the following command on Red Hat or CentOS Linux:
rpm --query --queryformat '%{NAME} %{VERSION} %{RELEASE} %{ARCH}\n' google-cloud-ops-agent
DEBIAN / UBUNTU
Run the following command on Debian or Ubuntu:
dpkg-query --show --showformat '${Package} ${Version} ${Architecture} ${Status}\n' google-cloud-ops-agent
SLES / SUSE
Run the following command on SUSE:
rpm --query --queryformat '%{NAME} %{VERSION} %{RELEASE} %{ARCH}\n' google-cloud-ops-agent
WINDOWS
Run the following command on Windows:
googet installed google-cloud-ops-agent
Restarting the agent
You must restart the Ops Agent to pick up changes in configuration files. To restart the agent, use the following instructions.
LINUX
Run the following command on your instance:
sudo service google-cloud-ops-agent restart
Windows
Connect to your instance using RDP or a similar tool and login to Windows.
Open a PowerShell terminal with administrator privileges by right-clicking the PowerShell icon and selecting Run as Administrator.
Run the following PowerShell command:
Restart-Service google-cloud-ops-agent -Force
Upgrading the agent
To upgrade the Ops Agent to the latest release, use the following instructions:
Google Cloud console
You can upgrade the Ops Agent by using Cloud Monitoring installation instructions. For more information, see Installing the agent using the Google Cloud console.
Linux
To upgrade the agent to the latest version, run the following command:
sudo bash add-google-cloud-ops-agent-repo.sh --also-install
To upgrade the agent to the latest point release of a specific major version, run the following command:
sudo bash add-google-cloud-ops-agent-repo.sh --also-install \
--version=MAJOR_VERSION.*.*
Windows
To upgrade to the latest agent release:
Connect to your instance using RDP or a similar tool and login to Windows.
Open a PowerShell terminal with administrator privileges by right-clicking the PowerShell icon and selecting Run as Administrator.
Copy-Item -Path "C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml" -Destination "C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.bak"
Run the following PowerShell commands to remove your installed agent and to run the installation command:
googet -noconfirm remove google-cloud-ops-agent googet -noconfirm install google-cloud-ops-agent
Listing all agent versions
To list the available versions of the agent, run the following command:
CENTOS / RHEL
List the available versions of the agent:
sudo yum list --showduplicates google-cloud-ops-agent
DEBIAN / UBUNTU
List the available versions of the agent:
sudo apt-cache madison google-cloud-ops-agent
SLES / SUSE
List the available versions of the agent:
sudo zypper search -s google-cloud-ops-agent
WINDOWS
List the available versions of the agent:
googet available google-cloud-ops-agent
Uninstalling the agent
To remove the Ops Agent and its configuration files, use the following instructions.
After you uninstall the agent, the Google Cloud console might take up to one hour to report this change.
Linux
Run the following command:
sudo bash add-google-cloud-ops-agent-repo.sh --uninstall
Windows
To uninstall the Ops Agent, follow the following steps:
Connect to your instance using RDP or a similar tool and login to Windows.
Open a PowerShell terminal with administrator privileges by right-clicking the PowerShell icon and selecting Run as Administrator.
Run the following PowerShell command:
googet -noconfirm remove google-cloud-ops-agent
VMs without remote package access
Installing the Ops Agent requires access to remote package repositories, for both the agent package and (on Linux) its dependencies.
If you are using VPC-SC or a private network, the network configuration might also affect your ability to install agent dependencies from upstream repositories. The agent packages themselves are accessible by using Private Google Access. This can be configured following Enable Private Google Access.
If your VM host's security policy denies access to remote package repositories, we recommend creating a custom VM image with the agent pre-installed and disabling package management in that image.
What's next
- Learn about what logs the agent sends to Cloud Logging using its default configuration.