Installing the Logging Agent

The Stackdriver Logging agent streams logs from your VM instances and from selected third party software packages to Stackdriver Logging. Using the agent is optional but we recommend it. The agent runs under both Linux and Microsoft Windows.

Before you begin

Check that the agent supports your VM instance and learn about Stackdriver accounts.

Supported VM instances

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

  • Google App Engine: You do not need the agent. Skip this page.
  • Google Container Engine: You do not need the agent. Skip this page.
  • Google 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.

For more information about the agent and the VM instances it supports, see Logging Agent.

Stackdriver accounts

Stackdriver accounts support billing and Stackdriver Monitoring services.

If you are using Compute Engine VM instances, then you can use Stackdriver Logging without a Stackdriver account. Without an account, your project has Basic Tier logging privileges.

If you are using Amazon EC2 VM instances, then you must link your AWS account to a Premium Tier Stackdriver account in order to use Stackdriver Logging.

For more information, see Service Tiers and Creating a Stackdriver account.

Installing on Linux and Windows

Use the following instructions to install the agent on VM instances running Linux or Microsoft Windows.

If you have problems with installation, see Troubleshooting.

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 two commands on your VM instance:

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

  3. Verify that the output of the preceding checksum command,sha256sum, is the same as the following:

    07ca6e522885b9696013aaddde48bf2675429e57081c70080a9a1364a411b395  install-logging-agent.sh
    

  4. Run the installation script with the following command:

    sudo bash install-logging-agent.sh

    You can delete the installation script when 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 an 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 /m
    
  3. Download and run the agent's installer using the following three PowerShell commands. You do not need administrator privileges.

    cd C:\Users\[USERNAME]
    invoke-webrequest https://dl.google.com/cloudagents/windows/StackdriverLogging-v1-3.exe -OutFile StackdriverLogging-v1-3.exe;
    .\StackdriverLogging-v1-3.exe
    

    Notes:

    • You must download the installer to a non-system directory, such as C:\Users\[USERNAME]. The installer does not run from system directories, including the directory C:\.

      If you download the installer to a system directory, move it to another directory.

    • The installer places the agent in the directory C:\GoogleStackdriverLoggingAgent\. You cannot presently change that directory.

    • You can delete the installer when it completes successfully.

Verifying the installation

To check that the installation was successful, look for the agent's test log entry in the Logs Viewer.

Go to the Logs Viewer

  1. At the top of the page, choose the project containing your VM instance:

    • For Compute Engine VM instances, choose the project that contains the VM instance.
    • For Amazon EC2 VM instances, choose the AWS LINK project that Stackdriver creates when you connect your AWS account to a Stackdriver account.
    • Do not choose a Stackdriver account project, unless that is the project containing your Compute Engine VM instance.
  2. In the logs menus, choose the resource for your VM instance:

    • For Compute Engine, choose GCE VM Instance.
    • For Amazon EC2, choose AWS EC2 Instance.
    • Select syslog (Linux), winevt.raw (Windows), or All logs.

If you see a log entry, "Successfully sent gRPC to Stackdriver Logging API," then the agent installation is complete. Otherwise, see Troubleshooting.

For more information about the Logs Viewer, see Logs Viewer.

Next steps

  • For more information about the agent, see The Logging Agent.

  • The agent streams logs from some third-party packages. For a list, see Logs From the Logging Agent. These logs are available only from VM instances running Linux.

  • The following sections on this page describe some common maintenance tasks.

Maintenance tasks

This section describes some common maintenance tasks.

Determining the agent's version

To find out the version of the running agent, do the following:

Linux instance

Run the following command on your instance:

    # For Debian and Ubuntu systems:
    dpkg -l google-fluentd

    # For Amazon Linux, Red Hat and CentOS systems:
    rpm -q google-fluentd

Windows instance

There is presently no way to determine the current agent version on Windows.

Restarting the agent

Restart the agent to pick up any changes to the agent's configuration:

Linux instance

Run the following command on your instance:

    sudo service google-fluentd reload

To stop and then start the Logging agent, run the following command on your instance:

    sudo service google-fluentd restart

After reloading or 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:

net stop fluentdwinsvc
net start fluentdwinsvc

Upgrading the agent

Upgrade the agent to the latest release.

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

The preceding commands do not change the agent's configuration file. To get a clean configuration file, run the following command on your instance:

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

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

Alternatively, you can remove the current agent and then install the most recent agent.

Windows instance

To upgrade to the latest agent release, install the newest agent as described in Installing on Windows. Any previous agent will be uninstalled.

Uninstalling the agent

To remove the Logging agent and its configuration files, do the following.

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

Windows instance

Uninstall the current agent by running the following program:

C:\GoogleStackdriverLoggingAgent\uninstall.exe

Testing the agent

If you suspect that the agent is not working, check that it is running and try to send a test message to Stackdriver Logging:

Linux instance

The following procedure works on both Compute Engine and Amazon EC2 VM instances running Linux:

  1. Verify that the agent is running by executing the following commands on your VM instance:

    ps ax | grep fluentd
    

    You should see output similar to the following:

     2284 ?        Sl     0:00 /opt/google-fluentd/embedded/bin/ruby /usr/sbin/google-fluentd [...]
     2287 ?        Sl    42:44 /opt/google-fluentd/embedded/bin/ruby /usr/sbin/google-fluentd [...]
    
  2. Send a test log message by running the following command on your VM instance:

    logger "Some test message"
    

Windows instance

The following procedure works on Compute Engine and Amazon EC2 VM instances running Windows:

  1. Verify that the agent is running by executing the following command on your VM instance, using PowerShell:

    Get-Service fluentdwinsvc
    

    You should see the following:

    Status    Name              DisplayName
    ------    ----              -----------
    Running  fluentdwinsvc      Fluentd Windows Service
    
  2. Requires Administrator privileges: Send a test log message by running the following PowerShell commands:

    New-EventLog   -LogName Application -Source "Test Source"
    Write-EventLog -LogName Application -Source "Test Source" -EntryType Information -EventID 1 -Message "Testing 123 Testing."
    

Finding your test message

After sending a test message, look for it in the Logs Viewer:

Go to the Logs Viewer

  1. At the top of the page, choose the project containing your VM instance:

    • For Compute Engine VM instances, choose the project that contains the VM instance.
    • For Amazon EC2 VM instances, choose the AWS LINK project that Stackdriver creates when you connect your AWS account to a Stackdriver account.
    • Do not choose a Stackdriver account project, unless that is the project containing your Compute Engine VM instance.
  2. In the logs menus, choose the resource for your VM instance:

    • For Compute Engine, choose GCE VM Instance.
    • For Amazon EC2, choose AWS EC2 Instance.
    • Select syslog (Linux), winevt.raw (Windows), or All logs.

Troubleshooting

The following table lists some common problems and tells you how to fix them.

The Logging agent records errors in /var/log/google-fluentd/google-fluentd.log. The error class, Google::APIClient::ClientError, indicates there is a problem with permissions or API access.

You can start seeing errors after the agent has been running successfully. For example, someone might have revoked the required permissions from your project or your VM instance.

Error Cause Solution
The agent's installer on Windows fails to run You might have downloaded the installer to a system directory. Move the installer to a non-system directory, such as C:\Users\[USERID]\.
Project has not enabled the API You have not enabled the Stackdriver Logging API in your project. Go to the APIs console and change the status of the Stackdriver Logging API to ON.
Request had invalid credentials
or
Unable to fetch access token (no scopes configured?)
Your VM instance does not have suitable credentials. If you are using Amazon EC2, then you must install credentials on your VM instances before installing the agent. See Authorizing the Agent to install credentials.
Authorization failed Your private-key authorization credentials for the Logging agent are not configured correctly. See Verifying private key credentials.
The caller does not have permission The service account used for authorization in your project has insufficient permissions. It might be the default service account used within Compute Engine or App Engine, or it might be a user-defined service account used for private key authorization. The account must have Can edit permission. Change the permission of the service account in your project's Permissions page.
Cannot obtain project ID The Logging agent failed to get the project ID from a service account's private key credentials file. To add or override a project ID for the agent, edit the agent's configuration file, google-fluentd.conf, on your VM instance. It appears in directory /etc/default/google-fluentd or /etc/sysconfig/google-fluentd. In the <match **> section, add the following line:
project_id [YOUR_PROJECT_ID]
Otherwise, see Authorizing the Agent to fix or replace the credentials.

Send feedback about...

Stackdriver Logging