Installing the Cloud Monitoring agent on a single VM

The Cloud Monitoring agent gathers system and application metrics from your VM instances and sends them to Monitoring. You can also configure the Monitoring agent to monitor third-party applications.

This guide explains how to install the Cloud Monitoring agent for Monitoring on Compute Engine and Amazon Elastic Compute Cloud (EC2) VMs. Using the agent is optional but recommended for Compute Engine VM instances. For these VMs, Monitoring can access some metrics from the VM's hypervisor without the agent, including CPU utilization, some disk traffic metrics, network traffic, and uptime. Using the agent is required for Amazon Elastic Compute Cloud (EC2) VMs.

On instances running Microsoft Windows, the agent records CPU utilization and memory, pagefile, and volume usage. If you are running IIS or SQL server, the agent collects metrics from those services by default.

Before you begin

To install the agent, ensure that you have the following:

VMs without remote package access

Installing the Monitoring 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.

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.

Installing the agent on a single VM

To install the agent, use the following instructions.

AMAZON LINUX AMI / CENTOS / RHEL

  1. Open a terminal connection to your VM instance using SSH or a similar tool and ensure you have sudo access.

  2. Change to a directory you have write access to, for example your home directory.

  3. Add the agent's package repository:

    curl -sSO https://dl.google.com/cloudagents/add-monitoring-agent-repo.sh
    sudo bash add-monitoring-agent-repo.sh
    
  4. Install the agent:

    1. List the available versions of the agent in order to select which version to install:

      sudo yum list --showduplicates stackdriver-agent
      
    2. For production environments, you might want to pin to a major version to avoid pulling in major versions that might include backward incompatible changes. To pin to a major version, run:

      sudo yum install -y stackdriver-agent-major-version.*
      

      For example, to pin to the 6.x.x of the agent, run:

      sudo yum install -y stackdriver-agent-6.*
      
    3. If you don't want to pin to a major version, you can select one of the other installation options:

      1. To install a specific version of the agent, run:

          sudo yum install -y stackdriver-agent-version-number
        
      2. To install the latest version of the agent, run:

          sudo yum install -y stackdriver-agent
        
  5. Start the agent service

    sudo service stackdriver-agent start
    

You can delete the installation script after it runs successfully.

  • To verify that the agent is working as expected, run:

    sudo service stackdriver-agent status
    

    The status of the agent should be OK.

  • You can also examine the logs and ensure there are no errors:

    sudo grep collectd /var/log/{syslog,messages} | tail
    

If you have trouble with the installation, refer to the Troubleshooting page.

DEBIAN / UBUNTU

  1. Open a terminal connection to your VM instance using SSH or a similar tool and ensure you have sudo access.

  2. Change to a directory you have write access to, for example your home directory.

  3. Add the agent's package repository:

    curl -sSO https://dl.google.com/cloudagents/add-monitoring-agent-repo.sh && \
    sudo bash add-monitoring-agent-repo.sh && \
    sudo apt-get update
    
  4. Install the agent:

    1. List the available versions of the agent in order to select which version to install:

      sudo apt-cache madison stackdriver-agent
      
    2. For production environments, you might want to pin to a major version to avoid pulling in major versions that might include backward incompatible changes. To pin to a major version, run:

      sudo apt-get install -y 'stackdriver-agent=major-version.*'
      

      For example, to pin to the 6.x.x of the agent, run:

      sudo apt-get install -y 'stackdriver-agent=6.*'
      
    3. If you don't want to pin to a major version, you can select one of the other installation options:

      1. To install a specific version of the agent, run:

          sudo apt-get install -y stackdriver-agent=version-number
        
      2. To install the latest version of the agent, run:

          sudo apt-get install -y stackdriver-agent
        

You can delete the installation script after it runs successfully.

  • To verify that the agent is working as expected, run:

    sudo service stackdriver-agent status
    

    The status of the agent should be OK.

  • You can also examine the logs and ensure there are no errors:

    sudo grep collectd /var/log/{syslog,messages} | tail
    

If you have trouble with the installation, refer to the Troubleshooting page.

SLES / SUSE

  1. Open a terminal connection to your VM instance using SSH or a similar tool and ensure you have sudo access.

  2. Change to a directory you have write access to, for example your home directory.

  3. Add the agent's package repository:

    curl -sSO https://dl.google.com/cloudagents/add-monitoring-agent-repo.sh
    sudo bash add-monitoring-agent-repo.sh
    
  4. Install the agent:

    1. List the available versions of the agent in order to select which version to install:

      sudo zypper search -s stackdriver-agent
      
    2. For production environments, you might want to pin to a major version to avoid pulling in major versions that might include backward incompatible changes. To pin to a major version, run:

      sudo zypper install -y 'stackdriver-agent<major-version.0.0'
      

      For example, to pin to the 6.x.x of the agent, run:

      sudo zypper install -y 'stackdriver-agent<7.0.0'
      
    3. If you don't want to pin to a major version, you can select one of the other installation options:

      1. To install a specific version of the agent, run:

          sudo zypper install -y stackdriver-agent=version-number
        
      2. To install the latest version of the agent, run:

          sudo zypper install -y stackdriver-agent
        
  5. Start the agent service

    sudo service stackdriver-agent start
    

You can delete the installation script after it runs successfully.

  • To verify that the agent is working as expected, run:

    sudo service stackdriver-agent status
    

    The status of the agent should be OK.

  • You can also examine the logs and ensure there are no errors:

    sudo grep collectd /var/log/{syslog,messages} | tail
    

If you have trouble with the installation, refer to the Troubleshooting page.

WINDOWS

To install the agent on a VM instance running Windows, perform the following steps:

  1. Connect to your instance using RDP or a similar tool and login to Windows.

  2. Open a PowerShell terminal with administrator privileges by right-clicking the PowerShell icon and selecting Run as Administrator.

  3. Run the following PowerShell command:

    (New-Object Net.WebClient).DownloadFile("https://repo.stackdriver.com/windows/StackdriverMonitoring-GCM-46.exe", "${env:UserProfile}\StackdriverMonitoring-GCM-46.exe")
    & "${env:UserProfile}\StackdriverMonitoring-GCM-46.exe"
    

    Alternatively, you can browse to the following URL to download and run the agent's installer:

    https://repo.stackdriver.com/windows/StackdriverMonitoring-GCM-46.exe

    To install the agent silently, append the /S option to the invocation of the installer:

    .\StackdriverMonitoring-GCM-46.exe /S
    

    In “silent” mode use the /D option to specify the installation directory, for example:

    .\StackdriverMonitoring-GCM-46.exe /S /D="C:\Google Cloud's operations suite\Monitoring\"
    

    You can delete the installer when it completes successfully.

    If you have trouble with the installation, refer to the Troubleshooting page.

Installing the agent on a Compute Engine VM

You can install the Monitoring agent on a single VM from the pre-configured Monitoring VM Instances dashboard.

To reach this dashboard, do the following:

  1. In the Cloud Console, select your Google Cloud project.
    Go to Cloud Console
  2. In the navigation pane, select Monitoring.

    If you have never used Cloud Monitoring, then on your first access of Monitoring in the Google Cloud Console, a Workspace is automatically created and your project is associated with that Workspace. Otherwise, if your project isn't associated with a Workspace, then a dialog appears and you can either create a Workspace or add your project to an existing Workspace. We recommend that you create a Workspace. After you make your selection, click Add.

  3. In the Monitoring navigation pane, select Dashboards.
  4. In the table of dashboards, locate the VM Instances entry, and then click on the name.

The Inventory tab on the VM Instances dashboard lists all VMs and contains a status column for the agent, as shown in the following screenshot:

The VM Instances dashboard in Monitoring shows the status
of
agents.

If the agent is not detected on a Compute Engine instance, you can click the "Not detected" link to bring up an installation workflow in the dashboard.

Optional tasks

This section describes how to perform common maintenance tasks.

Configuring the agent

To adjust the agent configuration, see Configuring the Monitoring agent.

Configuring an HTTP proxy

If you use an HTTP proxy for proxying requests to the Logging and Monitoring APIs, do the following:

LINUX

  1. Edit the following configuration file (should be created if does not exist):

    • For agent versions 6.0.0 and higher, edit:

      /etc/default/stackdriver-agent
      
    • For agent versions earlier than 6.0.0, edit the appropriate file for your OS:

      For Debian and Ubuntu, edit:

      /etc/default/stackdriver-agent
      

      For CentOS and SLES, edit:

      /etc/default/stackdriver-collectd
      
  2. Add the following lines:

     export http_proxy="http://proxy-ip:proxy-port"
     export https_proxy="http://proxy-ip:proxy-port"
     export no_proxy=169.254.169.254  # Skip proxy for the local Metadata Server.
    
  3. Restart the Monitoring agent by running the following command on your VM instance.

     sudo service stackdriver-agent restart
    

WINDOWS

  1. If you use an HTTP proxy, run the following command from an administrator command prompt. This sets the HTTP_PROXY and HTTPS_PROXY environment variables so that the agent can send data to Monitoring using outbound HTTPS:

    setx HTTP_PROXY http://proxy-ip:proxy-port /m
    setx HTTPS_PROXY http://proxy-ip:proxy-port /m
    setx no_proxy 169.254.169.254 /m
    

Determining the agent version

To determine the version of the Monitoring agent on your system, run the following commands on your VM instance:

AMAZON LINUX AMI / CENTOS / RHEL

Run the following command on Amazon Linux, Red Hat, or CentOS Linux:

rpm --query --queryformat '%{NAME} %{VERSION} %{RELEASE} %{ARCH}\n' \
     stackdriver-agent

DEBIAN / UBUNTU

Run the following command on Debian or Ubuntu:

dpkg-query --show --showformat \
    '${Package} ${Version} ${Architecture} ${Status}\n' \
     stackdriver-agent

SLES / SUSE

Run the following command on SUSE:

rpm --query --queryformat '%{NAME} %{VERSION} %{RELEASE} %{ARCH}\n' \
     stackdriver-agent

WINDOWS

There is presently no way to determine the version of the Monitoring agent running on Windows.

Restarting the agent

You must restart the Monitoring 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 stackdriver-agent restart

WINDOWS

  1. Connect to your instance using RDP or a similar tool and login to Windows.

  2. Open a PowerShell terminal with administrator privileges by right-clicking the PowerShell icon and selecting Run as Administrator.

  3. Run the following PowerShell command:

Restart-Service -Name StackdriverMonitoring

Upgrading the agent

To upgrade the Monitoring agent to the latest release, use the following instructions:

AMAZON LINUX AMI / CENTOS / RHEL

Run the following command on Amazon Linux, Red Hat, or CentOS Linux:

sudo yum update stackdriver-agent

DEBIAN / UBUNTU

Run the following commands on Debian or Ubuntu:

sudo apt-get update
sudo apt-get install -y stackdriver-agent

SLES / SUSE

Run the following command on SUSE:

sudo zypper update stackdriver-agent

If you're upgrading from an agent with version <= 6.0.5, you must restart the service manually:

sudo service stackdriver-agent restart

WINDOWS

To upgrade to the latest agent release, install the newest agent as described in Installing on Windows on this page. The installer prompts you to uninstall the previous version of the agent.

Uninstalling the agent

To remove the Monitoring agent and its configuration files, use the following instructions.

AMAZON LINUX AMI / CENTOS / RHEL

Run the following command on Amazon Linux, Red Hat, or CentOS Linux:

sudo yum remove stackdriver-agent

DEBIAN / UBUNTU

Run the following command on Debian or Ubuntu:

sudo apt-get remove stackdriver-agent

SLES / SUSE

Run the following command on SUSE Linux:

sudo zypper remove stackdriver-agent

WINDOWS

In the Windows Control Panel, choose Uninstall a program. You should see the Monitoring agent in the list of programs that you can uninstall.

Information about Google Cloud projects for AWS EC2 VM instances

When the documentation refers to the Google Cloud project associated with your VM instance, for EC2 VM instances, this phrase refers to the AWS connector project linked to your AWS account.

When you connect your AWS account to a Workspace, the AWS connector project is created. To identify the AWS connector project, go to the Workspace's Settings tab. The connector project are listed under the heading AWS Accounts. The Project ID column displays the Google Cloud projects associated with your Workspace.

Refer to the Workspace page for more information about AWS connector projects.