Installing the Logging Agent on a single VM

The logging 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 or Amazon Web Services (AWS) account.

    • When installing the Google Cloud's operations suite agent, a minimum of 250 MiB memory is required, but 1 GiB is recommended.

    Also ensure your VM is running a supported operating system.

  • Credentials on the VM instance that authorize communication with Cloud Logging or Cloud Monitoring. Compute Engine VM instances generally have the correct credentials by default. If either of the following scenarios applies to you, then you might not have the proper credentials and must complete the Authorizing the agent procedures:

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

    • Running very old Compute Engine instances or Compute Engine instances created without the default credentials.

    To check if you have the proper credentials, run the Verifying Compute Engine credentials procedures.

  • For AWS users, do the following:

    1. Connect your AWS account to a Google Cloud. For information about this process, see Viewing metrics for AWS accounts.

    2. Refer to the Google Cloud projects for AWS EC2 VM instances section for additional information.

  • For pricing information, go to Pricing for Google Cloud's operations suite.

  • If you're using 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 on a single VM

To install the agent, use the following instructions.

Installing the latest version of the agent

To install the latest version of the agent, complete the following steps.

Linux

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

    curl -sSO https://dl.google.com/cloudagents/add-logging-agent-repo.sh
    sudo bash add-logging-agent-repo.sh --also-install
    

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 commands:

    (New-Object Net.WebClient).DownloadFile("https://dl.google.com/cloudagents/windows/StackdriverLogging-v1-15.exe", "${env:UserProfile}\StackdriverLogging-v1-15.exe")
    & "${env:UserProfile}\StackdriverLogging-v1-15.exe"
    

Installing a specific version of the agent

To install a specific version of the agent, complete the following steps.

Linux

  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. Download the agent installation script:

    curl -sSO https://dl.google.com/cloudagents/add-logging-agent-repo.sh
    

    When running the add-logging-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 standalone Logging agent (StackdriverLogging).
    • --uninstall-standalone-monitoring-agent: Uninstalls the standalone Monitoring agent (StackdriverMonitoring).

    See the script comments for more information and example usage.

  4. Add the agent's package repository and install the agent:

    1. To list the available agent versions in order to select which version to install, refer to Listing all agent versions.

    2. 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-logging-agent-repo.sh --also-install \
        --version=MAJOR_VERSION.*.*
      

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

      sudo bash add-logging-agent-repo.sh --also-install \
        --version=1.*.*
      
    3. To install a specific version of the agent, run:

      sudo bash add-logging-agent-repo.sh --also-install \
        --version=MAJOR_VERSION.MINOR_VERSION.PATCH_VERSION
      
  5. Restart the agent service

    A restart is required for the configurations that are installed by the catch-all packages above to take effect.

    sudo service google-fluentd restart
    

You can delete the installation script after it runs successfully.

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

    sudo service google-fluentd status
    

    The status of the agent should be OK.

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

    tail /var/log/google-fluentd/google-fluentd.log
    

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

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.

    1. Run the following PowerShell commands:

      (New-Object Net.WebClient).DownloadFile("https://dl.google.com/cloudagents/windows/StackdriverLogging-v1-15.exe", "${env:UserProfile}\StackdriverLogging-v1-15.exe")
      & "${env:UserProfile}\StackdriverLogging-v1-15.exe"
      

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

    https://dl.google.com/cloudagents/windows/StackdriverLogging-v1-15.exe

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

    & "${env:UserProfile}\StackdriverLogging-v1-15.exe" /S
    

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

    & "${env:UserProfile}\StackdriverLogging-v1-15.exe" /S /D="C:\Stackdriver\Google Cloud's operations suite\"
    

    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 Google Cloud's operations suite 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.
  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 Install agent link to bring up an installation workflow in the dashboard.

Optional tasks

This section describes how to perform common maintenance tasks.

Enable structured logging

When you run the installation script on a Linux VM, the script by default installs the google-fluentd-catch-all package when the --also-install flag is present. In order to switch to structured logging, complete the following steps.

  1. Back up any local changes to /etc/google-fluentd/config.d/.

  2. Run one of the following commands, depending on your Linux distribution:

    • YUM:

      sudo yum uninstall -y google-fluentd-catch-all-config
      sudo yum install -y google-fluentd-catch-all-config-structured
      sudo service google-fluentd restart
      
    • APT:

      sudo apt-get remove -y google-fluentd-catch-all-config
      sudo apt-get install -y google-fluentd-catch-all-config-structured
      sudo service google-fluentd restart
      

For information about structured logging, refer to the structured logging guide.

Configuring the agent

The agent comes preconfigured to monitor certain known log locations. On Linux, those locations are described in the package google-fluentd-catch-all-config, which is automatically pulled in by the installation script. On Windows, the agent monitors the Windows Event Log by default.

To adjust the agent configuration, see Configuring the 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 (create the file if it doesn't already exist):

     /etc/default/google-fluentd
    
  2. Add the following to the file:

     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 agent by running the following command on your VM instance:

     sudo service google-fluentd 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 Google Cloud's operations suite 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 Google Cloud's operations suite 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' \
     google-fluentd ∖
     google-fluentd-catch-all-config ∖
     google-fluentd-catch-all-config-structured

DEBIAN / UBUNTU

Run the following command on Debian or Ubuntu:

dpkg-query --show --showformat \
    '${Package} ${Version} ${Architecture} ${Status}\n' \
     google-fluentd ∖
     google-fluentd-catch-all-config ∖
     google-fluentd-catch-all-config-structured

SLES / SUSE

Run the following command on SUSE:

rpm --query --queryformat '%{NAME} %{VERSION} %{RELEASE} %{ARCH}\n' \
     google-fluentd ∖
     google-fluentd-catch-all-config ∖
     google-fluentd-catch-all-config-structured

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:

     reg query HKLM\Software\Wow6432Node\Microsoft\Windows\CurrentVersion\Uninstall\GoogleStackdriverLoggingAgent\ /v Version
    

Restarting the agent

You must restart the Google Cloud's operations suite 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-fluentd restart

After restarting the Google Cloud's operations suite agent, you might want to send a test message.

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 StackdriverLogging

Upgrading the agent

To upgrade the Google Cloud's operations suite agent to the latest release, use the following instructions:

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

Listing all agent versions

To list the available versions of the agent, run the following command:

AMAZON LINUX AMI / CENTOS / RHEL

List the available versions of the agent:

sudo yum list --showduplicates google-fluentd

DEBIAN / UBUNTU

List the available versions of the agent:

sudo apt-cache madison google-fluentd

SLES / SUSE

List the available versions of the agent:

sudo zypper search -s google-fluentd

WINDOWS

Installing earlier versions of the agent on Windows is not supported.

Uninstalling the agent

To remove the Google Cloud's operations suite agent and its configuration files, use the following instructions.

Linux

Run the following command:

sudo bash add-logging-agent-repo.sh --uninstall

Windows

In the Windows Control Panel, choose Uninstall a program. You should see the Google Cloud's operations suite 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 Google Cloud, you create an AWS connector project. For information about this process, see Viewing metrics for AWS accounts.

To access the AWS connector project for an AWS account, do one of the following:

  • Use the Google Cloud Console project selector to identify the projects that match your AWS connector project naming conventions, and then select the specific project for your AWS account.

  • Identify the Google Cloud project whose metrics scope includes your AWS account metrics and select that project in the Google Cloud Console project selector. For this Google Cloud project, go to the Monitoring page and then select the Settings page. The Settings page lists the AWS connector projects. You can use the Google Cloud Console project selector to access the AWS connector project.

VMs without remote package access

Installing the Google Cloud's operations suite 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.

What's next