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
1
curl -O -L https://github.com/rapidloop/pgmetrics/releases/download/v1.13.0/pgmetrics_1.13.0_linux_amd64.tar.gz
2
tar xvf pgmetrics_1.13.0_linux_amd64.tar.gz
Copied!
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:1
./pgmetrics_1.13.0_linux_amd64/pgmetrics -h myhost -U myuser mydb
Copied!
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:
1
pgmetrics run at: 28 Mar 2019 11:03:50 AM (now)
2
3
PostgreSQL Cluster:
4
Name: 10/main
5
Server Version: 10.7 (Debian 10.7-1.pgdg90+1)
6
Server Started: 27 Mar 2019 11:24:31 AM (23 hours ago)
7
System Identifier: 6547510021216283340
8
Timeline: 1
9
Last Checkpoint: 27 Mar 2019 1:44:52 PM (21 hours ago)
10
Prior LSN: 2/7E30D140
11
REDO LSN: 2/7E321370 (80 KiB since Prior)
12
Checkpoint LSN: 2/7E3213A8 (56 B since REDO)
13
Transaction IDs: 548 to 1150825 (diff = 1150277)
14
Notification Queue: 0.0% used
15
Active Backends: 1 (max 200)
16
Recovery Mode? no
17
Copied!
The pgmetrics binary is also available for Windows and macOS.
2. Get pgdash CLI
1
curl -O -L https://github.com/rapidloop/pgdash/releases/download/v1.9.0/pgdash_1.9.0_linux_amd64.tar.gz
2
tar xvf pgdash_1.9.0_linux_amd64.tar.gz
Copied!
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
4. Create and Upload a Report
1
./pgmetrics_1.13.0_linux_amd64/pgmetrics --no-password -f json bench | ./pgdash_1.9.0_linux_amd64/pgdash -a YOUR-API-KEY report myserver1
Copied!
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):
1
PGPASSWORD=mypass pgmetrics -h host {args} | pgdash {args}
Copied!
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”.
Last modified 23d ago