Papertrail

This add-on is operated by Papertrail Inc.

The log management service we always wanted. Papertrail makes logs fun. Ish.

Papertrail

Last Updated: 10 March 2014

addons logging

Table of Contents

Papertrail is an add-on providing hosted log aggregation and management, including real-time tail, search, and alerts on application and platform logs.

Adding log management to an application provides truly realtime app visibility, faster troubleshooting, elegant alerting optimized for Heroku, and painless archives. Papertrail is accessible via Web browser, command-line client, and HTTP API.

Logs can be generated from any language or buildpack and are automatically routed to Papertrail. No code changes are necessary.

Provisioning the add-on

Papertrail can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:add papertrail
-----> Adding papertrail to sharp-mountain-4005... done, v18 (free)

After attaching the Papertrail add-on, provisioning is automatic. No app changes are needed.

All app and Heroku output should begin appearing in Papertrail within 10 seconds, and be realtime thereafter. Activation is typically immediate but may take up to 5 minutes to start.

Accessing logs

Here are five ways to access or open logs:

Dashboard

For more on the Papertrail dashboard, see event viewer tour or help.papertrailapp.com.

The Papertrail dashboard allows you to tail and search logs and configure the service, such as saving searches and alerts.

To access the dashboard, visit the Heroku apps web interface, select the application in question, and then select Papertrail from the Add-ons list.

The dashboard can also be accessed via the CLI:

$ heroku addons:open papertrail
Opening papertrail for sharp-mountain-4005…

Papertrail provides an optional plugin to tail and search logs from the heroku command-line utility. To use it, install Papertrail’s Heroku plugin on your local workstation(s).

This is optional and runs on your personal workstation(s), not as part of your Heroku app.

$ heroku plugins:install https://github.com/papertrail/papertrail-heroku-plugin

The plugin adds a heroku pt:logs command. See plugin README for usage or using CLI plugins for how plugins work. The plugin works with both Heroku Toolbelt and gem-based Heroku clients.

Bookmarkable URL

To browse directly to your app’s events on Papertrail, use the URL format:

https://api.heroku.com/myapps/<app name>/addons/papertrail:<plan name>

This URL uses heroku.com single sign-on without needing to navigate heroku.com. For example, for the app sharp-mountain-4005 which subscribes to papertrail:choklad, bookmark this URL:

https://api.heroku.com/myapps/sharp-mountain-4005/addons/papertrail:choklad

Command-line shortcut

To open Papertrail’s Web interface from the command-line, run heroku addons:open papertrail. For example:

$ heroku addons:open --app sharp-mountain-4005 papertrail

Your preferred browser will load Papertrail. To add a pt bash alias which does this, run:

$ echo "alias pt='heroku addons:open --app sharp-mountain-4005 papertrail'" >> ~/.bashrc

Archives

Papertrail automatically creates compressed log archive files on a daily or hourly basis. These are downloadable in Papertrail under Archives. Archives are retained for 1 year with all paid plans or 1 week with the free “choklad” plan.

Additionally, Papertrail can upload these archives to an S3 bucket in your own Amazon Web Services account. See “Account” to provide a bucket.

Each archive contains all logs in a tab-separated values (TSV) format. In addition to being human-readable, the TSVs are simple to parse or import into a data warehouse like Redshift or Hive/Hadoop on Elastic MapReduce.

Account status

To see account status, access Papertrail via the Dashboard and click the Account menu option.

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Use the heroku addons:upgrade command to migrate to a new plan. Upgrading and downgrading plans will not affect existing logs other than as necessary to apply the new plan options.

$ heroku addons:upgrade papertrail:newplan
-----> Upgrading papertrail:newplan to sharp-mountain-4005... done, v18 ($29/mo)
       Your plan has been updated to: papertrail:newplan

Removing the add-on

Papertrail can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:remove papertrail
-----> Removing papertrail from sharp-mountain-4005... done, v20 (free)

Before removing Papertrail, a data export can be performed by downloading logs from the Archives page.

Learn more

To learn about many additional features, check out Papertrail’s full documentation. Here are a few:

Support

All Papertrail support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome: join support chat, email support@papertrailapp.com, or visit help.papertrailapp.com.