Note: If you cannot find a topic, go to where all RightScale documentation will soon be located. Also, feel free to Chat with us!
Home > Partners > Papertrail > Documentation > Papertrail Setup and Runbook Guide

Papertrail Setup and Runbook Guide

Papertrail provides two (2) RightScripts to configure and send system syslog messages (such as /var/log/messages) and application log files (such as Rails’ production.log) to Papertrail.

Table of Contents

Setup Guide

The following steps will explain how to add the Papertrail RightScripts to an existing ServerTemplate so that any servers launched with that ServerTemplate will be set up for Papertrail. 


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

Create a Papertrail Account

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


Configures Papertrail log destination for system-wide OS syslog (with syslog-ng or rsyslog).

  • PAPERTRAIL_SYSLOG_HOSTNAME: Destination hostname. Example:
  • PAPERTRAIL_SYSLOG_PORT: Destination port. Example: 12345

Configures Papertrail log destination for app log files(s) (using small standalone remote_syslog daemon).

  • PAPERTRAIL_SYSLOG_HOSTNAME and PAPERTRAIL_SYSLOG_PORT (same values as papertrail_syslog.rb)
  • PAPERTRAIL_LOG_FILE_PATHS: Path(s) or glob(s) to app log files (comma-separated for multiple). Example: /home/rails/myapp/log/production.log, /var/log/mysql*.log


Add RightScript(s) to ServerTemplate

Go to the HEAD version of the ServerTemplate that you're going to enable for Papertrail functionality.

Go the ServerTemplate's Scripts tab and add one or both Papertrail RightScripts to the end of the boot script list.


Add a Server to a Deployment

Add a server to a deployment using the modified ServerTemplate that has the Papertrail RightScripts.  If you do not have a deployment, you must create one before you can add a server into it.  See Create a New Deployment.

See Add a Server to a Deployment.

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


Runbook Guide

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


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.

See also

You must to post a comment.
Last modified
23:42, 16 May 2013


This page has no custom tags.


This page has no classifications.



© 2006-2014 RightScale, Inc. All rights reserved.
RightScale is a registered trademark of RightScale, Inc. All other products and services may be trademarks or servicemarks of their respective owners.