Installing the Monitoring agent

This guide explains how to install the Stackdriver Monitoring agent for Monitoring on Compute Engine and Amazon Elastic Compute Cloud (EC2) virtual machine (VM) instances. For more information, see Supported VM instances.

Using the Monitoring agent is optional but recommended. Monitoring can access some metrics without the agent, including CPU utilization, some disk traffic metrics, network traffic, and uptime.

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 one of the following:

• A supported VM instance in a Google Cloud Platform (GCP) project or Amazon Web Services (AWS) account.
  • A minimum of 250 MiB of resident (RSS) memory is recommended to run the Monitoring agent.
• A Workspace monitoring the GCP project or AWS account containing the VM instance.

• Credentials on the VM instance that authorize communication with Stackdriver.

  • GCP VM instances generally have the correct credentials by default.

  • For AWS instances, you must install authorization credentials on your VMs before installing the agent.

GCP projects for AWS VM instances

Stackdriver documentation often refers to "the GCP project associated with your VM instance." For AWS VM instances, this refers to the AWS connector project linked to your AWS account.

Stackdriver creates the AWS connector project when you connect your AWS account to a Workspace. The connector project has the following attributes:

• A name that begins AWS Link
• An ID that begins with aws-

Use this ID as the ID for "the GCP project associated with your VM instance."

For more information, see Stackdriver Monitoring quickstart (AWS).

Note: Don't install the agent on an AWS VM instance until you have connected your AWS account to a Workspace. Until the connection is made, there is no associated GCP project and therefore nowhere to send monitoring data.

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

Authorizing the agent

Before installing the Monitoring agent, check that your VM instance has the credentials that the agent needs. The agent must have permission to send monitoring information to Monitoring. Permission is given by using service account credentials that are stored on your VM instance and serve as Application default credentials for the agent.

• If you are installing the agent on a Compute Engine VM instance, then the default service account on your instance should have the credentials needed by the agent. However, very old instances or instances created without the default credentials require private-key credentials. To verify your credentials, see the following section, Verifying Compute Engine credentials.

• If you are installing the agent on an Amazon EC2 VM instance, then there is no default service account. Instead, you must manually obtain private-key credentials from a service account of the AWS connector project. If you think your instance already has private-key credentials, then see Verifying private-key credentials to check them. To add private-key credentials, skip ahead to Adding credentials.

Adding credentials

If you are installing the agent on a Compute Engine VM instance and you created your instance with the default credentials, you can skip this section and go right to Installing on Linux or Installing on Windows. If you aren't sure whether you have the right credentials, see Verifying Compute Engine credentials.

If your Compute Engine instance doesn't have the correct credentials, or if you are installing the agent on an Amazon EC2 instance, then the following sections explain how to:

1. Create a service account with the required privileges and private-key credentials.
2. Copy the private-key credentials to your VM instance, where they serve as Application default credentials for software running on your instance.

Creating a service account

Use the IAM & Admin > Service accounts page of the GCP Console to create a service account and private key for the GCP project associated with your VM instance.

Open the IAM service account page

1. Click Select a project and choose the GCP project in which to create the service account:

   • For Compute Engine instances, choose the project in which you created the instance. If you created your instance in the Workspace hosting project, then choose the Workspace.

   • For Amazon EC2 instances, choose the AWS connector project created when you connected Monitoring your AWS account. The connector project's name typically begins with AWS Link. Don't create your service account in the Workspace project.

   Click Open. If there is no existing service account, a dialog prompts you to create one. Otherwise, you see the following Service Accounts page:

   

2. In the Service Accounts page, click Create service account.

3. In the Service account details pane, fill in the following information:

   1. Enter a service account name. For example, Agent service account.
   2. Enter a service account description.
   3. Click Create.

4. In the Service account permissions pane, fill in the following information:

   1. In the Select a role drop-down menu, select Monitoring > Monitoring Metric Writer. This authorizes the Monitoring agent.
   2. Click Add another role.
   3. In the new Select a role drop-down menu, select Logging > Logs Writer. This authorizes the Stackdriver Logging agent. Adding this role lets you use this service account to run both Stackdriver agents.
   4. Click Continue.

5. In the Grant users access to this service account pane:

   1. Click Create Key.
   2. Select JSON as the Key type.
   3. Click Create.

   After the key is created, the GCP Console writes the private-key file to your workstation's download directory and displays a pop-up dialog similar to the following:

   

6. Click Close in the pop-up window.

7. In the main Create service account page, click Done.

Copying the private key to your instance

For the added service account credentials to be recognized, you must copy the private-key file to one of the following locations on your VM instance, using whatever file-copy tool you wish:

• Linux only: /etc/google/auth/application_default_credentials.json
• Windows only: C:\ProgramData\Google\Auth\application_default_credentials.json
• Any location you store in the variable, GOOGLE_APPLICATION_CREDENTIALS. The variable must be visible to the agent's process.

For your convenience in the following instructions, set the environment variable CREDS to point to your credentials file. For example:

`CREDS="~/Downloads/{project_name}-{key_id}.json"`

The following file-copy instructions assume you have a Linux environment on both your workstation and your instance. If you are using a different configuration, consult the documentation from your cloud provider for how to copy the private-key file. In the previous step, Creating a service account, your private-key credentials should have been stored on your workstation at a location you saved in the variable CREDS:

Compute Engine

On your workstation, use the gcloud command-line tool:

REMOTE_USER="$USER"
INSTANCE="{your-instance-id}"
ZONE="{your-instance-zone}"
gcloud compute scp "$CREDS" "$REMOTE_USER@$INSTANCE:~/temp.json" --zone "$ZONE"

On your Compute Engine instance, run these commands:

APPLICATION_DEFAULT_CREDS="/etc/google/auth/application_default_credentials.json"
sudo mkdir -p /etc/google/auth
sudo mv "$HOME/temp.json" "$APPLICATION_DEFAULT_CREDS"
sudo chown root:root "$APPLICATION_DEFAULT_CREDS"
sudo chmod 0400 "$APPLICATION_DEFAULT_CREDS"

Amazon EC2

On your workstation, use scp:

KEY="{your-ssh-key-pair-file}"
INSTANCE="ec2-{your-instance's-public-ip}.{your-zone}.compute.amazonaws.com"
# The remote user depends on the installed OS: ec2-user, ubuntu, root, etc.
REMOTE_USER="ec2-user"
scp -i "$KEY" "$CREDS" "$REMOTE_USER@$INSTANCE:~/temp.json"

On your EC2 instance, run these commands:

APPLICATION_DEFAULT_CREDS="/etc/google/auth/application_default_credentials.json"
sudo mkdir -p /etc/google/auth
sudo mv "$HOME/temp.json" "$APPLICATION_DEFAULT_CREDS"
sudo chown root:root "$APPLICATION_DEFAULT_CREDS"
sudo chmod 0400 "$APPLICATION_DEFAULT_CREDS"

Next steps

Your VM instance now has the credentials that the agent needs.

• If you would like to double-check the credentials, see Verifying private-key credentials on this page.

• If you haven't yet installed the Monitoring agent, then go to Installing on Linux or Installing on Windows.

• If you have already installed the agent, then restart the agent so that it uses your new credentials. For example, use the following Linux command on your VM instance:

  sudo service stackdriver-agent restart
  

Installing on Linux

This step assumes you have a VM instance running Linux that is being monitored by a Workspace, and that your instance has the proper credentials for the agent. For more information, see Adding credentials. These instructions work for both Compute Engine instances and Amazon EC2 instances:

1. Run the following commands on your VM instance to install the monitoring agent:

   curl -sSO https://dl.google.com/cloudagents/install-monitoring-agent.sh
   sudo bash install-monitoring-agent.sh
   

   At the end of the installation, you should see something like the following message.

   Restarting services
   [ ok ] Restarting stackdriver-agent (via systemctl): stackdriver-agent.service.
   

2. If you use an HTTP proxy, do the following:

   1. Edit the Monitoring agent's system-defaults file to set PROXY_URL to the URL of your HTTP proxy. This URL comes from your configuration, not from a value Google provides. The name of the configuration file depends on your version of Linux:

      • For Debian and Ubuntu, edit /etc/default/stackdriver-agent
      • For Amazon Linux, Red Hat, CentOS, and SUSE, edit /etc/sysconfig/stackdriver

   2. Restart the Monitoring agent by running the following command on your VM instance.

      sudo service stackdriver-agent restart
      

You have finished installing the agent. If you have problems, see Troubleshooting.

Installing on Windows

To install the agent on a VM instance running Windows, perform the following steps after you have established an RDP or similar connection to your instance and have logged into Windows:

1. If you use an HTTP proxy, run the following command from an administrator command prompt to set the https_proxy environment variable so that the agent can send data to Monitoring using outbound HTTPS:

   setx https_proxy https://[YOUR_PROXY_SERVER_URI] /m
   

   Restart your shell for this setting to take effect.

2. Browse to the following URL. Download and run the agent's installer:

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

   This can also be done via the following PowerShell commands:

   cd $env:UserProfile;
   Invoke-WebRequest https://repo.stackdriver.com/windows/StackdriverMonitoring-GCM-46.exe -OutFile StackdriverMonitoring-GCM-46.exe;
   .\StackdriverMonitoring-GCM-46.exe
   

Your agent installation is now complete.

Caution: You must download the installer to a non-system directory, such as C:\Users\[USERNAME]. For security reasons, the installer doesn't run from system directories, including the directory C:\.
If you download the installer to a system directory, move it to another directory before running it.

Note: The agent installer also supports a “silent” option, /S, that can be used in scripting the installation.

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

.\StackdriverMonitoring-GCM-46.exe /S

Caution: Silent installation is an asynchronous operation. When the installation command exits, the agent is not yet installed. You can check for a successful installation by looking for the StackdriverMonitoring service.

Note: The installer places the agent in the C:\Program Files (x86)\Stackdriver\MonitoringAgent\ directory by default. You can change that directory during installation.

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

.\StackdriverMonitoring-GCM-46.exe /S /D="C:\Stackdriver\Monitoring\"

Note: You may delete the installer when it completes successfully.

Automated installation

Installation scripts for popular configuration managers, including Ansible, Chef, and Puppet, are provided by the vendors and other community members. We post links to new scripts as they become available.

Determining the agent version

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

Debian & Ubuntu

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

Amazon Linux

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

Red Hat & CentOS

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

SUSE

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

Microsoft Windows

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

Updating the agent

Note: If you have upgraded your instance's Linux operating system to a new major release, then you should first remove the Monitoring agent and then re-install the agent instead of upgrading it. See Removing the agent and Installing on Linux.

Use the commands from the following table to update your agent:

Debian & Ubuntu

Run the following commands on Debian or Ubuntu Linux:

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

Amazon Linux

Run the following command on Amazon Linux:

sudo yum update stackdriver-agent

Red Hat & CentOS

Run the following command on Red Hat or CentOS Linux:

sudo yum update stackdriver-agent

SUSE

Run the following command on SUSE Linux:

sudo zypper update stackdriver-agent

Microsoft Windows

To upgrade the Microsoft Windows agent, install the new agent version as described in Installing on Microsoft Windows. It removes any older agent you have installed.

Removing the agent

Use the commands from the following table to remove your agent:

Debian & Ubuntu

Run the following commands on Debian or Ubuntu Linux:

sudo apt-get purge stackdriver-agent

Amazon Linux

Run the following command on Amazon Linux:

sudo yum remove stackdriver-agent

Red Hat & CentOS

Run the following command on Red Hat or CentOS Linux:

sudo yum remove stackdriver-agent

SUSE

Run the following command on SUSE Linux:

sudo zypper remove stackdriver-agent

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

Troubleshooting

See the Troubleshooting page.