Installing the agent

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

Note: If you are running your VM in the App Engine or Google Kubernetes Engine environments, an agent is included in the VM image. Skip this page.

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

Before you begin

Check that the Stackdriver Logging agent supports your VM instance and learn about Workspaces. To learn more about the requirements and supported environments, see About the Stackdriver Logging agent.

Note: To use the Logging agent with Amazon EC2 VM instances, you must link your AWS account to a Workspace. For more information, see Stackdriver Pricing.

Supported VM instances

Some kinds of VM instances already contain the Logging agent or software similar to the Logging agent. For others, you should install the agent using the instructions on this page:

• Google Cloud Platform (GCP) VM instances:
  • App Engine: An agent is included in the VM image. Skip this page.
  • GKE: An agent is included in the VM image. Skip this page.
  • Compute Engine: Install the agent on your VM instances. The VM instances already have the required authorization. See Installing on Linux and Windows.
• Amazon EC2: Install authorization credentials on your VM instances, and then install the agent. See Authorizing the agent and then Installing on Linux and Windows.

When installing the Stackdriver Logging agent, a minimum of 250MB memory is required, but 1GB is recommended.

Stackdriver billing

If you are using AWS VM instances, then you must link your AWS account to a Workspace in order to use the Stackdriver Logging agent.

For more information, see Creating a Workspace.

Installing without remote package access

To install or upgrade the agent on a host whose security policy denies it access to remote package repositories:

1. Install the agent package on a host that can access:

   • Google Cloud package repository: packages.cloud.google.com
   • (For Kubernetes environments) Google Container Registry: gcr.io

2. Copy the package to the targeted host.

Installing on Linux and Windows

To install the agent on VM instances running Linux or Microsoft Windows, use the following instructions.

Beta

This is a beta release of the Logging agent for Windows. This feature might be changed in backward-incompatible ways and is not subject to any SLA or deprecation policy.

If you are trying to enable structured logging, refer to the installation instructions for structured logging.

Linux instance

1. Open a terminal connection to your VM instance using SSH or a similar tool.

2. Download the Logging agent's installation script by running the following command on your VM instance:

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

3. Run the installation script with the following command:

   sudo bash install-logging-agent.sh
   

You can delete the installation script after it runs successfully.

Windows instance

1. Open a terminal connection to your instance using RDP or a similar tool and login to Windows.

2. If you use HTTP proxy, run the following command from an administrator command prompt. This sets the http_proxy environment variable so that the agent can send data to Stackdriver Logging:

   setx http_proxy http://[YOUR_PROXY_SERVER_URI] /m
   

3. Open a PowerShell terminal, then run the following three PowerShell commands. You don't need administrator privileges.

   cd C:\Users\$env:Username
   Invoke-WebRequest https://dl.google.com/cloudagents/windows/StackdriverLogging-v1-8.exe -OutFile StackdriverLogging-v1-8.exe;
   .\StackdriverLogging-v1-8.exe
   

   Notes:

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

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

     .\StackdriverLogging-v1-8.exe /S
     

   • The installer places the agent in the following directory by default:

     C:\Program Files (x86)\Stackdriver\LoggingAgent\
     

     You can change that directory during installation.

   • You can delete the installer when it completes successfully.

To verify or test your installation of the Stackdriver Logging agent, see Verifying the agent installation.

If you have problems with installation, see Troubleshooting the Logging agent.

Additional tasks

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. If you want to adjust the agent configuration, see Configuring the Logging agent.

This section describes how to perform common maintenance tasks: determining the agent version, restarting the agent, upgrading the agent, and uninstalling the agent.

Determining the version

To identify the version of the Logging agent and its configuration components, run the following command:

Linux instance

Run the following command on your instance:

# For Debian and Ubuntu systems:
dpkg-query --show --showformat \
    '${Package;-45} ${Version;-10} ${Architecture;-8} ${Status;-25}\n' \
    google-fluentd \
    google-fluentd-catch-all-config \
    google-fluentd-catch-all-config-structured

# For Amazon Linux, Red Hat, CentOS, and SUSE systems:
rpm --query --queryformat \
    '%-45{NAME} %-10{VERSION} %-10{RELEASE} %-8{ARCH}\n' \
    google-fluentd \
    google-fluentd-catch-all-config \
    google-fluentd-catch-all-config-structured

Windows instance

Run the following command.

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

The preceding command returns an error if the agent's version is earlier than v1-5. Upgrade to the latest agent.

Restarting the agent

You must restart the Stackdriver Logging agent to pick up changes in configuration files. To restart the Stackdriver Logging agent, use the following instructions.

Linux instance

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 instance

Requires administrator privileges: To restart the agent, run the following commands on your VM instance in Command Prompt or PowerShell:

# For Logging agent version v1-5 and later.
net stop  StackdriverLogging
net start StackdriverLogging

# For Logging agents before v1-5.
net stop  fluentdwinsvc
net start fluentdwinsvc

Upgrading the agent

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

Linux instance

To upgrade to the latest agent release, run the following command on your instance:

# For Debian and Ubuntu systems:
sudo apt-get install --only-upgrade google-fluentd

# For Amazon Linux, Red Hat and CentOS systems:
sudo yum upgrade google-fluentd

# For SUSE systems:
sudo zypper update google-fluentd

The preceding commands don't change the agent's configuration file. To get the latest default configuration and catch-all configuration files, run the following commands on your instance:

# For Debian and Ubuntu systems:
sudo apt-get install --only-upgrade -o Dpkg::Options::="--force-confnew" google-fluentd-catch-all-config
sudo apt-get install --only-upgrade google-fluentd

# For Amazon Linux, Red Hat and CentOS systems:
sudo yum upgrade google-fluentd google-fluentd-catch-all-config

# For SUSE systems:
sudo zypper update google-fluentd google-fluentd-catch-all-config

Alternatively, you can remove the current agent and then install the most recent agent. This is the recommended approach when performing upgrades that might cause configuration changes (e.g. in case of a major version bump).

Windows instance

To upgrade to the latest agent release, install the newest agent as described in Installing on Windows. You are prompted to uninstall the previous version of the agent.

Uninstalling the agent

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

Note: If you added your own fluentd configuration files, copy them out of the agent's configuration directory for safekeeping.

Linux instance

Uninstall the current Linux agent:

# For Debian and Ubuntu systems:
sudo service google-fluentd stop
sudo apt-get remove google-fluentd google-fluentd-catch-all-config

# For Amazon Linux, Red Hat and CentOS systems:
sudo service google-fluentd stop
sudo yum remove google-fluentd google-fluentd-catch-all-config

# For SUSE systems:
sudo service google-fluentd stop
sudo zypper remove google-fluentd google-fluentd-catch-all-config

Windows instance

Uninstall the current agent by running the following command:

[AGENT_INSTALLATION_DIRECTORY]\uninstall.exe

If you are running the Logging agent versions v1-5 and later, use the directory that you chose when installing the agent. The default installation directory is:

C:\Program Files (x86)\Stackdriver\LoggingAgent\

If you are running a Logging agent before v1-5, the installation directory is:

C:\GoogleStackdriverLoggingAgent\

For more information, see Configuring the Logging agent.