Getting started with pgexporter
First of all, make sure that pgexporter is installed and in your path by
using "pgexporter -?". You should see
pgexporter 0.3.2
Prometheus exporter for PostgreSQL
Usage:
pgexporter [ -c CONFIG_FILE ] [ -u USERS_FILE ] [ -d ]
Options:
-c, --config CONFIG_FILE Set the path to the pgexporter.conf file
-u, --users USERS_FILE Set the path to the pgexporter_users.conf file
-A, --admins ADMINS_FILE Set the path to the pgexporter_admins.conf file
-Y, --yaml METRICS_FILE_DIR Set the path to YAML file/directory
-d, --daemon Run as a daemon
-V, --version Display version information
-?, --help Display help
If you don't have pgexporter in your path see our
README
on how to compile and install pgexporter in your system.
Configuration
Lets create a simple configuration file called
pgexporter.conf with the content
[pgexporter]
host = *
metrics = 5002
log_type = file
log_level = info
log_path = /tmp/pgexporter.log
unix_socket_dir = /tmp/
[primary]
host = localhost
port = 5432
user = pgexporter
In our main section called
[pgexporter] we setup pgexporter to listen on all
network addresses. We will enable Prometheus metrics on port 5002.
Logging will be performed at "info" level and
put in a file called "/tmp/pgexporter.log". Last we specify the
location of the "unix_socket_dir" used for management operations.
Next we create a section called
[primary] which has the information about our
PostgreSQL instance. In this case it is running
on "localhost" on port "5432" and we will use the "pgexporter" user account to connect.
The "pgexporter" user must have the "pg_monitor" role and have access to the "postgres" database,
so for example
CREATE ROLE pgexporter WITH NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION LOGIN PASSWORD 'secretpassword';
GRANT pg_monitor TO pgexporter;
and in pg_hba.conf
local postgres pgexporter scram-sha-256
host postgres pgexporter 127.0.0.1/32 scram-sha-256
host postgres pgexporter ::1/128 scram-sha-256
We will need a user vault for the "pgexporter" account, so the following commands will add
a master key, and the "pgexporter" password
pgexporter-admin master-key
pgexporter-admin -f pgexporter_users.conf add-user
We are now ready to run pgexporter.
See
Configuration for all configuration options.
Running
We will run pgexporter using the command
pgexporter -c pgexporter.conf -u pgexporter_users.conf
If this doesn't give an error, then we are ready to use the Prometheus endpoint.
pgexporter is stopped by pressing Ctrl-C (^C) in the console where you started it, or by sending
the SIGTERM signal to the process using "kill pid".
Run-time administration
pgexporter has a run-time administration tool called pgexporter-cli.
You can see the commands it supports by using "pgexporter-cli -?" which will give
pgexporter-cli 0.3.2
Command line utility for pgexporter
Usage:
pgexporter-cli [ -c CONFIG_FILE ] [ COMMAND ]
Options:
-c, --config CONFIG_FILE Set the path to the pgexporter.conf file
-h, --host HOST Set the host name
-p, --port PORT Set the port number
-U, --user USERNAME Set the user name
-P, --password PASSWORD Set the password
-L, --logfile FILE Set the log file
-v, --verbose Output text string of the result
-V, --version Display version information
-?, --help Display help
Commands:
is-alive Is pgexporter alive
stop Stop pgexporter
status Status of pgexporter
details Detailed status of pgexporter
reload Reload the configuration
reset Reset the Prometheus statistics
To stop pgexporter you would use
pgexporter-cli -c pgexporter.conf stop
Check the outcome of the operations by verifying the exit code, like
echo $?
or by using the -v flag.
If pgexporter has both Transport Layer Security (TLS) and "management" enabled then pgexporter-cli can
connect with TLS using the files ~/.pgexporter/pgexporter.key (must be 0600 permission),
~/.pgexporter/pgexporter.crt and ~/.pgexporter/root.crt.
Administration
pgexporter has an administration tool called pgexporter-admin, which is used to control user
registration with pgexporter.
You can see the commands it supports by using "pgexporter-admin -?" which will give
pgexporter-admin 0.3.2
Administration utility for pgexporter
Usage:
pgexporter-admin [ -f FILE ] [ COMMAND ]
Options:
-f, --file FILE Set the path to a user file
-U, --user USER Set the user name
-P, --password PASSWORD Set the password for the user
-g, --generate Generate a password
-l, --length Password length
-V, --version Display version information
-?, --help Display help
Commands:
master-key Create or update the master key
add-user Add a user
update-user Update a user
remove-user Remove a user
list-users List all users
In order to set the master key for all users you can use
pgexporter-admin -g master-key
The master key must be at least 8 characters.
Then use the other commands to add, update, remove or list the current user names, f.ex.
pgexporter-admin -f pgexporter_users.conf add-user
Next Steps
Next steps in improving pgexporter's configuration could be
- Update pgexporter.conf with the required settings for your system
- Enable Transport Layer Security v1.2+ (TLS)
See
Configuration for more information on these subjects.
Tutorials
There are some short tutorials available to help you better understand and configure pgexporter:
Closing
The
pgexporter community hopes that you find
the project interesting.
Feel free to
All contributions are most welcome !
Consider giving the project a
star on
GitHub if you find it useful.
