This add-on is operated by Papertrail Inc.
The log management service we always wanted. Papertrail makes logs fun. Ish.
Last updated 13 October 2015
Table of Contents
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.
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:create 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.
Here are five ways to access or open logs:
- Dashboard (primary)
herokuplugin to tail and search
- Bookmarkable URL
- Command-line shortcut
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…
heroku command-line plugin
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 heroku-papertrail
The plugin adds a
heroku pt command. See using CLI plugins for how plugins work. The plugin works with both Heroku Toolbelt and gem-based Heroku clients.
To link directly to your app’s events on Papertrail, use the URL format:
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:
To dynamically generate “Show related logs” links from an internal admin site (often with a search query for requests from a certain user ID or IP, or a timestamp of a key event), see linking to logs.
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
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.
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.
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:destroy 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.
To learn about many additional features, check out Papertrail’s full documentation. Here are a few:
Terms of Service
By installing the Papertrail Add-on, you agree to the Papertrail Software Services Agreement.
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: email firstname.lastname@example.org, join support chat, or visit help.papertrailapp.com.