Heroku Postgres Metrics Logs

Last updated April 29, 2025

Heroku Postgres Standard and Premium Tier database users see database-related events on their app’s log stream. These events are useful for recording and analyzing usage over time.

You can view your Postgres logs with the Heroku CLI, the dashboard, your logging add-on, or in your log drain. You can also install a platform monitoring add-on to help monitor these metrics.

Heroku Postgres metrics that appear via heroku-postgres are separate from standard alerts emitted from Postgres itself that appear for all applications via postgres.

For example, to get postgres logs, run the command heroku logs -p postgres -a app-name. To get heroku-postgres logs, run the command heroku logs -p heroku-postgres -a app-name for Cedar-generation apps and heroku logs -s heroku-postgresql -a app-name for Fir apps.

Log Format

You can view Heroku Postgres metrics logs with heroku logs.

For example, the Heroku Postgres metrics logs can look like:

2024-03-15T12:10:39.000000+00:00 app[heroku-postgres]: source=HEROKU_POSTGRESQL_SILVER addon=postgresql-devcenter-123456 sample#current_transaction=54017686 sample#db_size=16012956319bytes sample#tables=97 sample#active-connections=7 sample#waiting-connections=0 sample#index-cache-hit-rate=0.9239 sample#table-cache-hit-rate=0.93609 sample#load-avg-1m=0 sample#load-avg-5m=0 sample#load-avg-15m=0 sample#read-iops=0 sample#write-iops=0.13333 sample#tmp-disk-used=33849344 sample#tmp-disk-available=72944943104 sample#memory-total=4044960kB sample#memory-free=46920kB sample#memory-cached=3667532kB sample#memory-postgres=20824kB sample#wal-percentage-used=0.06512959334021144

For Fir-generation apps, the logs appear as heroku-postgresql[logs] instead.

The following attributes appear in application logs for all Standard and Premium-tier databases:

  • source: The database attachment name that the measurements relate to, for example, HEROKU_POSTGRESQL_VIOLET.
  • addon: The database addon name that the measurements relate to, for example, postgres-metric-68904.
  • The log line’s timestamp is the time at which the measurements were taken.

Filtering Logs

You can filter for Heroku Postgres metrics logs on a specific app.

For Cedar-generation apps:

$ heroku logs -p heroku-postgres -a example-app

For Fir-generation apps:

$ heroku logs -s heroku-postgresql -a example-app

Database Metrics

These attributes apply to a particular database:

  • sample#db_size: The number of bytes contained in the database. This metric includes all table and index data on disk, including database bloat.
  • sample#db-max-size: The maximum number of bytes available in the database.
  • sample#db-size-percentage-used: Percentage of storage used on the database, between 0.0–1.0.
  • sample#tables: The number of tables in the database.
  • sample#active-connections: The number of connections established on the database.
  • sample#waiting-connections: Number of connections waiting on a lock to be acquired. If many connections are waiting, this metric can be a sign of mishandled database concurrency.
  • sample#max-connections: The maximum number of connections available in the database.
  • sample#connections-percentage-used: Percentage of total connections used on the database, between 0.0–1.0.
  • sample#current_transaction: The current transaction ID, used to track writes over time.
  • sample#index-cache-hit-rate: Ratio of index lookups served from the shared buffer cache, rounded to five decimal points. Heroku recommends a value of 0.99 or greater if possible. If your index hit rate is consistently less than 0.99, investigate your Expensive Queries or upgrade your database plan for more RAM.
  • sample#table-cache-hit-rate: Ratio of table lookups served from the shared buffer cache, rounded to five decimal points. Heroku recommends a value of 0.99 or greater if possible. If your table hit rate is consistently less than 0.99, upgrade your database plan for more RAM.
  • sample#follower-lag-commits: Replication lag, measured as the number of commits that this follower is behind its leader. Replication is asynchronous so a number greater than zero doesn’t indicate an issue, however an increasing value deserves investigation. Read more in Monitoring Followers. We only have this metric for follower databases.
  • sample#primary-available and sample#standby-available: For databases with high availability, a value of 1 denotes database availability and a 0 denotes database outage.
  • sample#service-available: For databases without high availability, a value of 1 denotes database availability and a 0 denotes database outage.
  • sample#rollback-from: For databases that support rollback, the log either shows the timestamp of the earliest available rollback point or capturing-snapshot if the first backup is in progress.

Server Metrics

These metrics come directly from the server operating system:

  • sample#load-avg-1m, sample#load-avg-5m, and sample#load-avg-15m: The average system load over a period of 1 minute, 5 minutes, and 15 minutes, divided by the number of available CPUs. A load-avg of 1.0 indicates that, on average, processes were requesting CPU resources for 100% of the timespan. This number includes I/O wait. For databases that have burstable performance, a baseline load average is guaranteed. For more information see the burstable performance section in the technical characteristic article.
  • sample#read-iops and sample#write-iops: The number of read or write operations in I/O sizes of 16-KB blocks.
  • sample#max-iops: The maximum number of IOPS available in the database.
  • sample#iops-percentage-used: Percentage of IOPS used on the database, between 0.0–1.0.
  • sample#memory-total: Total amount of server memory available.
  • sample#memory-free: The amount of free memory available in KB.
  • sample#memory-cached: The amount of memory used by the OS for page cache, in KB.
  • sample#memory-postgres: The amount of memory used by Postgres in KB.
  • sample#memory-percentage-used: Percentage of server memory used on the database, between 0.0–1.0.
  • sample#tmp-disk-used, sample#tmp-disk-available: The number of bytes used and available on tmp mount.
  • sample#wal-percentage-used: Percentage of the WAL disk that has been used, between 0.0–1.0. See Postgres Write-Ahead Log Usage for more details.

The operating system is designed to maximize the amount of memory it uses for its page cache, but can sometimes release that memory if an application requests it. For an estimate of the total amount of memory available to your server, add sample#memory-free and sample#memory-cached together.

PgBouncer Metrics

We include these metrics for any Heroku Postgres server that has a PgBouncer pooler attachment. These metrics are a subset of the metrics viewable by running the SHOW POOLS; command when connected to PgBouncer’s special internal database:

  • sample#client_active: The number of client connections to the pooler with an active server connection assignment.
  • sample#client_waiting: The number of client connections to the pooler waiting for a server connection assignment.
  • sample#server_active: The number of server connections currently assigned to a client connection.
  • sample#server_idle: The number of server connections that aren’t currently assigned to a client connection.
  • sample#max_wait: The longest wait time of any client currently waiting for a server connection assignment.
  • sample#avg_query: The average query time of all queries executed through pooled connections.
  • sample#avg_recv: The number of bytes received from clients per second.
  • sample#avg_sent: The number of bytes sent to clients per second.

Replication Slot Metrics

These metrics display in the logs if you have pg-replication-slot-logs set to on.

  • spill_bytes: The number of bytes that spilled to disk or another storage medium, typically when memory is insufficient.
  • spill_count: The number of times data spilled to disk or another storage medium.
  • spill_txns: The number of transactions that involved data spilling.
  • stream_bytes: The number of bytes that streamed, possibly in a data stream or network stream.
  • stream_count: The number of stream operations or events that occurred.
  • stream_txns: The number of transactions that involved streaming.
  • total_bytes: The total number of bytes processed or handled by the system.
  • total_txns: The total number of transactions processed by the system.

Feedback

Log in to submit feedback.