This add-on is operated by SolarWinds Worldwide, LLC
Frustration-free log management. Papertrail makes logs fun. Ish.
Papertrail
Last updated March 14, 2019
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: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.
Accessing logs
Here are five ways to access or open logs:
- Dashboard (primary)
herokuplugin to tail and search- Bookmarkable URL
- Command-line shortcut
- Archives
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…
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 CLI and gem-based Heroku clients.
Bookmarkable URL
To link directly to your app’s events on Papertrail, use the URL format:
https://addons-sso.heroku.com/apps/<app name>/addons/papertrail
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://addons-sso.heroku.com/apps/sharp-mountain-4005/addons/papertrail
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.
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: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.
Learn more
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.
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: email support@papertrailapp.com, join support chat, or visit help.papertrailapp.com.