Getting Started

View a quick screencast at https://asciinema.org/a/190659 to get an overview of the steps detailed below to get pgDash setup:

1. Get pgmetrics

curl -O -L https://github.com/rapidloop/pgmetrics/releases/download/v1.17.1/pgmetrics_1.17.1_linux_amd64.tar.gz
tar xvf pgmetrics_1.17.1_linux_amd64.tar.gz

pgmetrics is the open-source collection agent for pgDash. This is available as a single, zero-dependency, statically-linked binary executable that you can copy to your $PATH. You can download this from GitHub here, or see other install options here. Once downloaded, try invoking it and seeing a report for your database:

./pgmetrics_1.17.1_linux_amd64/pgmetrics -h myhost -U myuser mydb

The command-line syntax is almost exactly the same as for psql and other utilities. Environment variables (like PGHOST, PGPORT, PGSSLMODE, PGPASSFILE etc) and files like ~/.pgpass, ~/.postgresql/postgresql.crt are also understood by pgmetrics.

You should see an output similar to this:

pgmetrics run at: 28 Mar 2019 11:03:50 AM (now)

PostgreSQL Cluster:
    Name:                10/main
    Server Version:      10.7 (Debian 10.7-1.pgdg90+1)
    Server Started:      27 Mar 2019 11:24:31 AM (23 hours ago)
    System Identifier:   6547510021216283340
    Timeline:            1
    Last Checkpoint:     27 Mar 2019 1:44:52 PM (21 hours ago)
    Prior LSN:           2/7E30D140
    REDO LSN:            2/7E321370 (80 KiB since Prior)
    Checkpoint LSN:      2/7E3213A8 (56 B since REDO)
    Transaction IDs:     548 to 1150825 (diff = 1150277)
    Notification Queue:  0.0% used
    Active Backends:     1 (max 200)
    Recovery Mode?       no

The pgmetrics binary is also available for Windows and macOS.

2. Get pgdash CLI

curl -O -L https://github.com/rapidloop/pgdash/releases/download/v1.12.1/pgdash_1.12.1_linux_amd64.tar.gz
tar xvf pgdash_1.12.1_linux_amd64.tar.gz

The command-line tool for uploading reports to the pgDash website is also available from GitHub here. This too is a single binary that can be placed anywhere.

3. Get Your API Key

Once you signup for pgDash, you can copy the API key from your profile page.

4. Create and Upload a Report

./pgmetrics_1.17.1_linux_amd64/pgmetrics --no-password -f json bench | ./pgdash_1.12.1_linux_amd64/pgdash -a YOUR-API-KEY report myserver1

The pgdash report command will upload the report in JSON format, piped to it from pgmetrics into https://app.pgdash.io/. “myserver1” is a friendly name to identify your database server -- we recommend the hostname of the server you're connecting to.

For this to work successfully, pgmetrics should be able to complete without asking for a password (this step is meant to be automated and run as a cron job). You can use the usual techniques (.pgpass file, client certificates, trust/peer authentication in pg_hba.conf), or even supply the password using the environment variable PGPASSWORD (although this is not recommended):

PGPASSWORD=mypass pgmetrics -h host {args} | pgdash {args}

Tips:

1. If the command appears to hang, it's probably waiting for you enter the password.

2. If you get a 429 error, it means you've hit a rate limit. Wait for 60 seconds before trying again.

5. That’s It!

You should now be able to see the report in pgDash after logging in.

You can repeat this command say, every 10 minutes or so, and see the timeseries graphs populating under “myserver1”.

Learn more about automating this operation.