Last updated October 29, 2025

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.

In addition to log aggregation and management, Papertrail enables you to monitor and analyze the metrics that impact your business at all levels of the stack. It provides everything you need to visualize, analyze, and actively alert on the metrics that matter to you. It integrates seamlessly with Heroku to provide you with out-of-the-box detailed information about your application’s performance, per-dyno system resources, and PostgreSQL database.

From there, you can build tailored charts and workspaces and set threshold-based alerts. Collaboration is supported through multi-user access.

Provisioning the add-on

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

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

After successful provisioning, the native log-based metrics described below will automatically begin flowing into a Papertrail pre-configured to provide a basic overview of your application and database performance. It may take 2-3 minutes for data to begin showing up. You can go to the Papertrail interface now to check things out or read on to learn more!

Accessing logs

Here are five ways to access or open logs:

• Dashboard (primary)
• heroku plugin to tail and search
• Bookmarkable URL
• Command-line shortcut
• Archives

Metrics

Native log-based metrics

After provisioning the add-on, Papertrail immediately begins collecting native Heroku metrics directly from your application’s log stream.

Router metrics are present in every Heroku application log stream and provide detailed information (including timing) about every request serviced by your application. As these details are sourced directly from the Heroku routing layer itself, it’s the truest measure of performance as experienced by your customers, accounting for any delays introduced by Heroku in addition to your application’s processing. Papertrail calculates a rich set of summary statistics (described below in custom distributions) including 50th percentile (median), 95th percentile, 99th percentile and 999th percentile latency that provide unprecedented insight into your application’s performance. The metrics (described in the linked Heroku router docs) available in Papertrail currently are:

• heroku.router.http.requests [app_name, dyno, method, source, status_category,status_code] - Request count by application name, dyno, HTTP status code, and method. Metrics capture all 200, 300, 400 and 500-level status codes from the Heroku Router for your applications.

• heroku.router.service.response_time [app_name, dyno, method, source, status_category, status_code] - Amount of time in milliseconds for the application to respond to a HTTP request

  • heroku.router.service.response_time.p50 - 50th percentile response time
  • heroku.router.service.response_time.p95 - 95th percentile response time
  • heroku.router.service.response_time.p99 - 99th percentile response time
  • heroku.router.service.response_time.p999 - 999th percentile response time

• heroku.router.connect.latency [app_name, dyno, method, source, status_category, status_code] - Amount of time in milliseconds spent establishing a connection to the backend web process

  • heroku.router.connect.latency.p50 - 50th percentile connect latency
  • heroku.router.connect.latency.p95 - 95th percentile connect latency
  • heroku.router.connect.latency.p99 - 99th percentile connect latency
  • heroku.router.connect.latency.p999 - 999th percentile connect latency

• heroku.router.bytes [app_name, dyno, method, source, status_category, status_code] - Number of bytes transferred from the backend web process to the client.

Postgres metrics are present in the log stream of any Heroku application with a provisioned Heroku Postgres database on a standard or premium tier. These metrics are summary statistics gathered by the Heroku Postgres service and are reported directly into Papertrail:

• heroku.postgres.load.load1 [app_name, database, addon]

• heroku.postgres.load.load5 [app_name, database, addon]

• heroku.postgres.load.load15 [app_name, database, addon]

• heroku.postgres.mem.total [app_name, database, addon]

• heroku.postgres.mem.free [app_name, database, addon]

• heroku.postgres.mem.cache [app_name, database, addon]

• heroku.postgres.mem.postgres [app_name, database, addon]

• heroku.postgres.mem.used [app_name, database, addon]

• heroku.postgres.db.size [app_name, database, addon]

• heroku.postgres.db.size_used [app_name, database, addon]

• heroku.postgres.db.tables [app_name, database, addon]

• heroku.postgres.db.connections_active [app_name, database, addon]

• heroku.postgres.db.connections_waiting [app_name, database, addon]

• heroku.postgres.db.current_transaction [app_name, database, addon]

• heroku.postgres.db.index_cache_hit_rate [app_name, database, addon]

• heroku.postgres.db.table_cache_hit_rate [app_name, database, addon]

• heroku.postgres.db.read_iops [app_name, database, addon]

• heroku.postgres.db.write_iops [app_name, database, addon]

Per-dyno runtime metrics are available to any Heroku application, but must be enabled by the user, as they are disabled by default. They provide insight into both memory usage and CPU load of each dyno and are reported with source tag values of the dyno’s logical role e.g. web.1 or worker.2. You can enable them with the following commands:

$ heroku labs:enable log-runtime-metrics

Enabling log-runtime-metrics for ... done

$ heroku restart

Once enabled, your per-dyno runtime metrics will automatically begin showing up in your Papertrail account. These metrics are summary statistics gathered by the Heroku Runtime layer and are reported directly into Papertrail under their given names.

• heroku.dyno.load.load1 [app_name, dyno, source]

• heroku.dyno.load.load5 [app_name, dyno, source]

• heroku.dyno.load.load15 [app_name, dyno, source]

• heroku.dyno.mem.rss [app_name, dyno, source]

• heroku.dyno.mem.swap [app_name, dyno, source]

• heroku.dyno.mem.cache [app_name, dyno, source]

• heroku.dyno.mem.total [app_name, dyno, source]

• heroku.dyno.mem.pgout [app_name, dyno, source]

• heroku.dyno.mem.pgin [app_name, dyno, source]

• heroku.dyno.mem.quota [app_name, dyno, source]

Error metrics counts and breakdowns of common Heroku errors:

• heroku.errors.http [app_name, dyno, method, source, status_category, status_code, code code_description] - Request count breakdown by Heroku HTTP errors (codes Hxx).

• heroku.errors.logging [app_name, code, code_description]- Number of log messages affected by logging errors (codes Lxx).

• heroku.errors.runtime [app_name, code, code_description]- Count of Heroku runtime errors (codes Rxx).

Custom log-based metrics

In addition to seamlessly extracting native metrics provided by Heroku, Papertrail’ log enables you to publish your own custom metrics directly through the Heroku log stream. Simply write your measurements to standard output (stdout) using one of the formats specified below and Papertrail will automatically detect and collect your custom metrics.

Once you collect custom metrics, you can build dashboards and set up alerts with them.

The examples below are in Ruby syntax but can be replicated in any language that permits writing to standard output.

Custom counting

Count log lines are used to submit increments to Papertrail. You can submit increments as frequently as desired and every minute the current total will be flushed to Papertrail and reset to zero. For example the following combination would result in a value of 5 being recorded for the enclosing minute in a Papertrail metric named user.clicks:

$ stdout.puts("count#user.clicks=1")
$ stdout.puts("count#user.clicks=1")
$ stdout.puts("count#user.clicks=3")

Aggregation is done on a per-tag basis; in the following case, user.clicks for user_id=1 receives a count of 1, while user_id=2 receives a count of 4:

$ stdout.puts("count#user.clicks=1 tag#user_id=2")
$ stdout.puts("count#user.clicks=1 tag#user_id=1")
$ stdout.puts("count#user.clicks=3 tag#user_id=2")

More on tagging below.

Custom distributions

Measure log lines are used to submit individual measurements that comprise a statistical distribution. The most common use case are timings i.e. latency measurements, but it can also be used to represent non-temporal distributions such as counts. You can submit as many measures as you’d like (typically they are submitted per-request) and every minute Papertrail will calculate/record a complete set of summary statistics over the measures submitted in that interval:

• min - The smallest value.

• max - The largest value.

• average - The average of all values.

• percentile 50 (median) - The value that falls precisely in the middle of all values. Considered a good indicator of typical application performance.

• percentile 95 - The value that is larger than 95% of all values.

• percentile 99 - The value that is larger than 99% of all values.

• percentile 999 - The value that is larger than 99,9% of all values.

• sum - The total of all values.

• count - The total number of values submitted.

Measures are submitted in a similar fashion to counts:

$ stdout.puts("measure#database.query=200ms")

Note that measures create five separate metrics in Papertrail based on the submitted measure name. Using the example above, you would find:

• database.query - A complex metric that contains the avg/count/last/max/min/sum values. You can switch between them using Papertrail’s Metrics Explorer.

• database.query.p50 - The median value.

• database.query.p95 - The 95th percentile value.

• database.query.p99 - The 99th percentile value.

• database.query.p999 - The 999th percentile value.

All metrics are aggregated for each combination of the provided tags; more on tagging below.

Custom sample metrics

Sample metrics are used to convey simple key/numerical value pairs when you are already calculating some kind of summary statistic in your app and merely need a simple transport mechanism to Papertrail. Typically you would submit sample metrics on some periodic tick and set said period on the metric in Papertrail. This example would create a metric in Papertrail with the name database.size:

$ stdout.puts("sample#database.size=40.9MB")

Metrics are aggregated for each combination of the provided tags; more on tagging below.

Tagged metrics

Papertrail metrics support multidimensional tagging, meaning that you can associate a particular observation with one or more attributes you would like to be able to query/report on. In Heroku logging, this is done using a syntax of tag#tag1=value1 tag#tag2=value2 on the same line as the measurement being recorded (before or after the measurement itself). In addition use can also use special tag called the source=val that will be parsed the same way as tag#source=val.

For example, we can track the rate of requests to our API by both endpoint and customer, as well as by both:

$ stdout.puts("count#api.volume=1 tag#api_endpoint=lookup tag#customer_id=123")

Dashboard

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 Metric Dashboards

System Dashboards

Papertrail offers comprehensive system dashboards to monitor, visualize, and analyze metrics for Heroku applications. Users can create custom dashboards tailored to their needs. These dashboards aggregate essential system performance data and provide actionable insights to maintain application health and diagnose issues swiftly.

• Overview Dashboard: Provides full visibility into app health by tracking key metrics like availability, latency, throughput, and database resources. It monitors average availability and request times at multiple percentiles, revealing user experience insights. HTTP status codes and error breakdowns quickly spot error trends or spikes. Router and connection latency views—including median, 95th, and 99th percentiles—show service and network bottlenecks. Postgres metrics like memory and load averages track backend health. Together, these metrics enable fast anomaly detection, root cause analysis, and proactive tuning to keep apps reliable and optimize user experience.

• Error Metrics: This dashboard shows application errors by tracking key HTTP, runtime, and logging error codes across services. Stacked visuals highlight trends and spikes from crashes, timeouts, dyno issues, resource limits, and logging failures. Monitoring these codes helps detect disruptions early, speeds troubleshooting, and provides insights to reduce downtime and boost system reliability. It is vital for Heroku app health and stability.

• HTTP Status Codes: This dashboard categorizes HTTP status codes: success (2xx), redirection (3xx), client error (4xx), and server error (5xx). It offers insights by dyno, host, and service to spot request and response issues. Real-time monitoring helps teams quickly find trends and problems in Heroku apps, improving reliability and troubleshooting.

• Postgres Metrics: Monitor database health with dashboards that display query timings, active and waiting connections, database size, cache hit rates, and IOPS. These metrics help identify bottlenecks and performance regressions in the database layer.

• Dyno Runtime: These dashboards track memory usage (RSS, swap, cache, total), CPU load, and quota for each dyno, enabling targeted troubleshooting and resource optimization at the process level.

Custom Dashboards

Custom dashboards let teams track key metrics, KPIs, and events tied to their goals. They support focused monitoring of chosen metrics, adaptable views for different users or settings, and highlight indicators beyond standard dashboards. These can be customized with flexible charts and workspaces.

Learn More

Users can filter and view only the charts associated with a specific app_name, allowing focused analysis of data relevant to that application. This filter dynamically updates all chart displays to reflect metrics, performance indicators, or visual summaries exclusive to the chosen app, enabling targeted examination without interference from unrelated datasets.

Metric Explorer

A metric is a measurable characteristic or occurrence related to an observed entity, such as the average CPU utilization of a network device. Metric values can be used to evaluate performance or identify potential problems.

Learn more

Alert

You can create alerts that are triggered by metric or attribute values or by log events. The type of alert you create determines how you define the condition or conditions that trigger the alert.

Metric-Based Alerts

Metric alerts are triggered when a metric or attribute value crosses a threshold, is not being reported, or meets another condition that you specify.

Log-Based Alerts

Log alerts monitor incoming log messages, including syslog messages, SNMP traps, audit logs, and Windows event logs. The condition that triggers the alert can be defined based on a combination of factors, including the source IP address, text included in the message, and the severity level.

Learn more

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

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

Picking Plan

For the Papertrail add-on, we offer two plan categories: a log-only plan and a log-with-metrics plan. Customers can select plans based on their monitoring needs.

Log Plans

The free Choklad plan meets basic log aggregation and management needs. Several plans are available, depending on your usage and monitoring requirements. Each plan includes log filtering, alerts, saved searches, and a dashboard, with options for log volume and retention days based on usage.

Log and Metric Plans

The free Development plan provides essential information about your application running on Heroku. It includes logs, log filtering, alerts, saved searches, a dashboard, native router/Postgres metrics, and displays the last hour of data in a single pane. To access native runtime metrics, record custom metrics, configure alerts, or view more than the last hour’s data, you’ll need to upgrade to a paid plan.

Depending on your usage level, several plans are available. Each plan includes log aggregation and management, native router and Postgres metrics, with increasing capacity for additional metrics. This capacity is consumed by both native runtime metrics (which scale with the number of dynos) and custom metrics. When selecting a plan, consider the number of custom metrics you intend to track and, if you’ve enabled runtime metrics, the number of dynos.

Note that a plan’s metric quota is limited by individual metric streams, not unique metric names. For example, tracking the runtime metric memory_total on 10 dynos counts as 10 metric streams towards your quota.

Per-dyno runtime metrics are available to any Heroku application but are currently disabled by default. If you enable runtime metrics (which we highly recommend), each dyno adds 10 metric streams.

To choose the right plan, multiply the number of dynos by 9, add the number of custom metrics, and compare the total with the plan’s metric allocation. For instance, if you run an app with 25 dynos and plan to track 50 custom metrics, your total metric count is:

25 x 9 = 225 (dyno runtime metric streams) + 50 (custom metric streams) = 275 metric streams. In this case, you would select the Gold plan, which allocates 300 metric streams.

Migrating from AppOptics and Librato AddOn

The migration is required due to the formal deprecation and end-of-support of the AppOptics and Librato Heroku add-ons by SolarWinds. Transitioning to Papertrail ensures continued observability and alignment with supported monitoring solutions.

Steps:

• Keep the existing AppOptics/Librato add-on active.

• Install the Papertrail add-on with the required plan (Log + Metric plan recommended) or, if already installed, change the billing plan to Logs + Metrics.

• Configure Papertrail to start collecting logs and metrics using billing plans Elements Marketplace: Papertrail (Plans & Pricing)

• Verify data flow in both systems (AppOptics/Librato and Papertrail).

• Alerts and User Dashboards: Recreate critical alerts and custom dashboards in Papertrail to match existing configurations. Use alert templates and out-of-the-box dashboards for faster setup.

• System Dashboards: Default system dashboards in Papertrail provide similar visibility and metrics coverage as those in AppOptics/Librato, minimizing reconfiguration effort.

Option 1: With Data Continuity (Parallel Operation)

Objective: Maintain access to historical data during the transition.

• Run both systems in parallel for the defined overlap period (for example 2–4 weeks).

• Remove the AppOptics/Librato add-on. Remove AppOptics Remove Librato

Once removed, access to AppOptics/Librato dashboards, metrics, and historical data will be permanently lost. Ensure any required configurations or exports are completed beforehand.

Option 2: Without Data Continuity (Immediate Cutover)

Objective: Switch monitoring systems immediately without retaining old data.

• Remove the AppOptics/Librato add-on. Remove AppOptics Remove Librato

Once removed, access to AppOptics/Librato dashboards, metrics, and historical data will be permanently lost. Ensure any required configurations or exports are completed beforehand.

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

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.

$ 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:

• Alerts
• Event viewer
• Gmail-style search
• Log filtering
• System logs

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.