Console
Start free

Installing the Cloud Logging agent on individual VMs

The Logging agent streams logs from your VM instances and from selected third-party software packages to Cloud Logging. It is a best practice to run the Logging agent on all your VM instances.

The VM images for Compute Engine don't include the Logging agent, so you must complete these steps to install it on those instances. The agent runs under both Linux and Windows.

If your VMs are running in Google Kubernetes Engine or App Engine, the agent is already included in the VM image, so you can skip this page.

Before you begin

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

Install the agent from the command line

To install the agent using the command line, use the following instructions.

Install 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. Download and run the agent-installation script by using the following commands:

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

    After it is installed, the agent is started automatically.

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-22.exe", "${env:UserProfile}\StackdriverLogging-v1-22.exe")
& "${env:UserProfile}\StackdriverLogging-v1-22.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. For version information, see List all agent versions.
    • --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.

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

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.

    1. Run the following PowerShell commands:

      (New-Object Net.WebClient).DownloadFile("https://dl.google.com/cloudagents/windows/StackdriverLogging-v1-22.exe", "${env:UserProfile}\StackdriverLogging-v1-22.exe")
& "${env:UserProfile}\StackdriverLogging-v1-22.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-22.exe

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

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

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

    & "${env:UserProfile}\StackdriverLogging-v1-22.exe" /S /D="C:\Stackdriver\Logging\"

    You can delete the installer when it completes successfully.

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

    Viewing agent information by using the Google Cloud console

    You can find status information about the agent on the pre-configured Monitoring VM Instances dashboard. To reach this dashboard, do the following:

    In the Google Cloud console, go to the VM Instances page:

    Go to VM Instances

    If you use the search bar to find this page, then select the result whose subheading is Monitoring.

    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 VM Instances dashboard in Monitoring shows the status of agents.

    The Agent column reports the following values:

    You can install the Ops Agent by doing the following:

    You can also install or update the Ops Agent from the VM Details page for a specific VM.

    When possible, the agent is installed by using an Ops Agent OS policy. For more information, see Manage VMs covered by the Ops Agent OS policy. Ops Agent OS policies aren't supported on all versions of all operating systems. In this case, clicking Install/Update Ops Agent provides a series of commands to run in Cloud Shell.

    The Ops Agent collects both metrics and logs by default. You can change this default behavior by configuring the Ops Agent.

    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:

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

    Configuring the Logging 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 Configure the Logging agent.

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

    Determine the agent version

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

    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

    Restart the agent

    You must restart the Logging 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 Logging 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

    Upgrade the agent

    To upgrade the Logging 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-logging-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-logging-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.

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

    Uninstall the agent

    To remove the Logging 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-logging-agent-repo.sh --uninstall

    Optionally, to remove the repository in addition to uninstalling the agent, append --remove-repo to the previous command.

    Windows

    In the Windows Control Panel, choose Uninstall a program. You should see the Logging agent in the list of programs that you can uninstall. You can also run uninstall.exe from the directory where you installed the Logging agent.

    VMs without remote package access

    Installing the Logging 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