Papertrail Setup and Runbook Guide

Prerequisites

• 'designer' and 'actor' user role privileges in the RightScale account

Create a Papertrail Account

Visit https://papertrailapp.com/ and sign-up for a new account  (free, no credit card required). Immediately after signing up, you’ll be shown a page titled "Quick Start." On that page, click Add Systems. 

This Setup Systems page will show a Papertrail log destination, such as: logs.papertrailapp.com:12345. You will need to provide these values as inputs for the Papertrails scripts. 

Note: A single Papertrail log destination can be used on hundreds of systems (across many Deployments and Clouds). You can also create additional destinations in Papertrail later.

Import the Papertrail RightScripts

Most users will want both scripts, though the scripts can be used individually. Both RightScripts should be used as boot scripts in a ServerTemplate.

Log into the RightScale dashboard and go to Design -> MultiCloud Marketplace -> RightScripts. Use the search tool to find and import the most recent revisions of both "Papertrail" RightScripts. A copy of the scripts will be saved in your RightScale account's local collection. (Design -> RightScripts)

See screenshot of configured inputs below.

Define Inputs

You will need to define any missing inputs for any boot/decomission scripts before you can successfully launch the server.

The following inputs must be specified for the successful execution of the Papertrail scripts.  It's recommended that you define the inputs at the deployment level.  If you are using both Papertrail scripts, you will see the following inputs:

• PAPERTRAIL_LOG_FILE_PATHS - Enter the path(s) or wildcard glob(s) to one or more app logs. For example,
  • to watch a single Rails request file, enter: /home/rails/myapp/log/production.log
  • to watch that file plus all files in a directory and certain files in another directory, enter:
    /home/rails/myapp/log/production.log, /var/log/apt/*, /var/log/mysql/log/*.log
• PAPERTRAIL_SYSLOG_HOSTNAME - Enter the Papertrail log hostname.  For example: logs.papertrailapp.com
• PAPERTRAIL_SYSLOG_PORT - Enter the Papertrail log port. For example: 12345

Launch the Server

Launch the server.  The Papertrail scripts will be executed at boot time when the server is launched.  The scripts will perform the following actions:

• install remote_syslog Ruby gem
• create /etc/log_files.yml with Papertrail destination
• start remote_syslog daemon

Once the server becomes operational, app log events from the files you specified will begin streaming to Papertrail immediately. Log in and visit the Papertrail log viewer to watch them appear in realtime.

Compatibility Note

The syslog script has been tested on the following RightImages (using the syslog daemon that each includes):

• RightImage_CentOS_5.4_i386_v5.6 - 11H2.a1 [rev 2]
• RightImage_CentOS_5.6_i386_v5.7 [rev 3]
• RightImage CentOS Linux 6.0 i386 [rev 1]
• RightImage_Ubuntu_10.04_i386_v5.6 - 11H1 [rev 13]

It should work on any system with a typical rsyslog or syslog-ng configuration.

The app log script should work on any system with a modern Ruby installation and RubyGems.

Generate Test Message

This will rarely be needed on production systems with any log volume.

To generate a test syslog message, run this command-line command: logger “Test message”

It should appear in the Papertrail log viewer within 2 seconds.

Adding and Removing App Log Files

Change the PAPERTRAIL_LOG_FILE_PATHS input and re-run the script manually (or reboot).

Reboots

Both scripts operate predictably during a reboot.

The syslog script checks for an already-configured log destination that matches its hostname input. If it finds one, it does nothing. If it does not find one, it treats this as an initial invocation and runs as described above.

The app log script regenerates /etc/log_files.yml and daemonizes remote_syslog at boot. It only installs (or upgrades) the Ruby gem when invoked manually.