=head1 NAME

pg_activity - Realtime PostgreSQL database server monitoring tool

=head1 SYNOPSIS

B<pg_activity> [option..] [connection string]

=head1 DESCRIPTION

Command line tool for PostgreSQL server activity monitoring.

pg_activity must run on the same server as the instance and
as the user running the instance (or root) to show
CPU, MEM, READ or WRITE columns and other system information.

=head2 THE HEADER

The first line of the header displays PostgreSQL's version, the host name, the
connection string and the refresh rate.

The rest of the header displays the following information: 

=over 2

=item - B<Size>: size of the database you are connected to - Growth in B/s;

=item - B<Mem.>: percentage of memory used - memory used / memory available;

=item - B<Swap>: percentage of  swap used - swap used / swap available;

=item - B<Load>: CPU load;

=item - B<TPS>: transaction per second (sum of commit & rollback for all databases / time elapsed since last snap);

=item - B<IO Max>: the number of IO per second (aggregated data gathered with the psutil library);

=item - B<Read>: current Read throughput (aggregated data gathered with the psutil library);

=item - B<Write>: current Write throughput (aggregated data gathered with the psutil library);

=item - B<Active connections>: number of active connections;

=item - B<Duration mode>: query, transaction or backend.

=back

=head2 THE RUNNING QUERIES PANEL

The running queries panel shows all running queries, transactions or backends 
(depending on the B<DURATION_MODE> setting) which have lasted for more than
B<min duration> seconds. It displays the following information:

=over 2

=item - B<PID>: process id of the backend which executes the query;

=item - B<DATABASE>: database specified in the connection string;

=item - B<APP>: application name specified in the connection string;

=item - B<USER>: user name specified in the connection string;

=item - B<CLIENT>: client address or "local" in case of linux socker connection;

=item - B<CPU%>: percentage of CPU used by the backend as reported by the psutil library;

=item - B<MEM%>: percentage of memory used by the backend as reported by the psutil library;

=item - B<READ/s>:  read thruput as reported by the psutil library;

=item - B<WRITE/s>: write thruput as reported by the psutil library;

=item - B<TIME>: time since the beginning of the query / transaction / backend start depending on the B<DURATION_MODE> currently in use;

=item - B<Waiting>: for PostgreSQL 9.6+: a specific wait event or nothing. Otherwise, a boolean indicating if we are waiting for a Lock;

=item - B<IOW>: boolean indicating that the process is waiting for IO as reported by the psutil library;

=item - B<state>: state of the backend;

=item - B<Query>: the query.

=back

=head2 THE WAITING QUERIES PANNEL

The waiting queries view displays queries that are wainting for a lock. It
shows the following information:

=over 2

=item - B<PID>: process id of the backend which executes the query;

=item - B<DATABASE>: database specified in the connection string;

=item - B<APP>: application name specified in the connection string;

=item - B<USER>: user name specified in the connection string;

=item - B<CLIENT>: client address or "local" in case of linux socker connection;

=item - B<RELATION>: the name of the relation being locked if applicable;

=item - B<TYPE>: the type of lock;

=item - B<MODE>: the mode of the lock;

=item - B<TIME+>: the duration of the query, transaction or session depending on the B<DURATION_MODE> setting;

=item - B<state>: the state of the transaction;

=item - B<Query>: the query.

=back

=head2 THE BLOCKING QUERIES PANNEL

The blocking queries view displays the queries that lock an object which is
requiered by another session. It shows following information:

=over 2

=item - B<PID>: process id of the backend which executes the query;

=item - B<DATABASE>: database specified in the connection string;

=item - B<APP>: application name specified in the connection string;

=item - B<USER>: user name specified in the connection string;

=item - B<CLIENT>: client address or "local" in case of linux socker connection;

=item - B<RELATION>: the name of the relation being locked if applicable;

=item - B<TYPE>: the type of lock;

=item - B<MODE>: the mode of the lock;

=item - B<TIME+>: the duration of the query, transaction or session depending on the B<DURATION_MODE> setting;

=item - B<Waiting>: for PostgreSQL 9.6+: a specific wait event or nothing. Otherwise, a boolean indicating if we are waiting for a Lock;

=item - B<state>: the state of the transaction;

=item - B<Query>: the query.

=back

=head1 COMMAND-LINE OPTIONS

=over 2

=item B<-U USERNAME>, B<--username=USERNAME>

	Database user name.

=item B<-p PORT>, B<--port=PORT>

	Database server port.

=item B<-h HOSTNAME>, B<--host=HOSTNAME>

	Database server host or socket directory.

=item B<-d DBNAME>, B<--dbname=DBNAME>

    Database name to connect to.

=item B<--blocksize=BLOCKSIZE>

	Filesystem blocksize (default: 4096).

=item B<--rds>

	Enable support for AWS RDS.

=item B<--output=FILEPATH>

	Store running queries as CSV.

=item B<--no-db-size>

	Skip total size of DB.

=item B<-w DISPLAY_MODE, --query-display-mode=DISPLAY_MODE>

	Queries display mode. Values: 1-TRUNCATED, 2-FULL(default), 3-INDENTED

=item B<--duration-mode=DURATION_MODE>

	Duration mode. Values: 1-QUERY(default), 2-TRANSACTION, 3-BACKEND

=item B<--min-duration=SECONDS>

	Don't display queries with smaller than specified duration (in seconds).

=item B<--help>

	Show this help message and exit.

=item B<--version>

	Show program's version number and exit.

=back

=head1 ENVIRONMENT VARIABLES

=over 2

All the environnement variables supported by libpq (PostgreSQL's query
protocol) are supported by pg_activity.

See: https://www.postgresql.org/docs/current/libpq-envars.html

=back

=head1 DISPLAY OPTIONS

=over 2

=item B<--no-pid>

	Disable PID.

=item B<--no-database>

	Disable DATABASE.

=item B<--no-user>

	Disable USER.

=item B<--no-client>

	Disable CLIENT.

=item B<--no-cpu>

	Disable CPU%.

=item B<--no-mem>

	Disable MEM%.

=item B<--no-read>

	Disable READ/s.

=item B<--no-write>

	Disable WRITE/s.

=item B<--no-time>

	Disable TIME+.

=item B<--no-wait>

	Disable W.

=item B<--no-app-name>

	Disable App.

=back

=head1 INTERACTIVE COMMANDS

=over 2

=item B<r>     Sort by READ/s, descending.

=item B<w>     Sort by WRITE/s, descending.

=item B<c>     Sort by CPU%, descending.

=item B<m>     Sort by MEM%, descending.

=item B<t>     Sort by TIME+, descending.

=item B<T>     Change duration mode: query, transaction, backend

=item B<Space> Pause on/off.

=item B<v>     Change queries display mode: full, truncated, indented

=item B<UP / DOWN> Scroll process list.

=item B<k / j> Scroll process list.

=item B<q>     Quit

=item B<+>     Increase refresh time. Maximum value: 3s

=item B<->     Decrease refresh time. Minimum Value: 1s

=item B<F1/1>  Running queries monitoring.

=item B<F2/2>  Waiting queries monitoring.

=item B<F3/3>  Blocking queries monitoring.

=item B<h>     Help page.

=item B<R>     Refresh.

=item B<D>     Refresh database size.

=back

=head1 NAVIGATION MODE

=over 2

=item B<UP / k>    Move up the cursor.

=item B<DOWN / j>  Move down the cursor.

=item B<K>     Terminate the current backend/tagged backends.

=item B<C>     Cancel the current backend/tagged backends.

=item B<Space> Tag or untag the process.

=item B<q>     Quit.

=item B<Other> Back to activity.

=back

=head1 EXAMPLES

PGPASSWORD='mypassword' pg_activity -U pgadmin -h 127.0.0.1 --no-client

pg_activity -h /var/run/postgresql

pg_activity -h myserver -p 5433 -d nagios -U nagios

=cut
