#####################
POSTGRESTATS LICENSE
#####################
Copyright 2013 NWLYNX <http://www.nwlynx.com/>.

This file is part of PostgreStats <http://www.postgrestats.com/>.

PostgreStats is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

PostgreStats is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with PostgreStats. If not, see <http://www.gnu.org/licenses/>.


INSTALLATION OF POSTGRESTATS IS SIMPLE.
BELOW IS A COMPLETE, DOCUMENTED 1-2-3 GUIDE TO GET YOU UP AND RUNNING QUICKLY.
NOTE: These scripts require both Root and your PostgreSQL SU to execute.


##############################################################################
1. Upload the PostgreStats install archive to your database server and unpack.
##############################################################################
FTP/SCP the PostgreStats.tar.gz install archive to your database server. Note: it can be installed anywhere you prefer but should be installed into a directory you can view online, whether through a site you have already set-up VIA Apache, or a new site you set-up specifically to view PostgreStats online. Unzip and extract the install folder by issuing the following command in the shell:

tar -zxf PostgreStats.tar.gz


########################################
2. Configure the PostgreStats conf file.
########################################
The main conf file is located in your install directory: postgrestats/scripts/conf.php. Vi/Vim into the conf file and customize the parameters you see listed. This file is documented heavily to help you understand what each parameter is used for. It's here you'll also set-up parameters for optional features such as whether you want to run vacuum / analyze after each log update (off by default), whether to use PHP / Apache basic authentication, auto back-up, email completion / summary report, etc.


###############################################
3. Verify PostgreSQL Stat Collector is running.
###############################################
If you know that the Stat Collector process is running already and collecting statistics, you can skip this step. In newer versions of PostgreSQL, the Stat Collector is on by default. For these versions, PostgreStats only requires the postgresql.conf line track_counts be set to "on", also the default. For older versions of Postgres, the following postgresql.conf file lines should be set to "on": stats_start_collector, stats_block_level and stats_row_level.

If you've changed these values, first restart the PostgreSQL service. To verify the Stat Collector is collecting statistics, PSQL into any database in your implementation and issue this query:

SELECT * FROM pg_stat_database;


#########################################
4. Execute the first Log Update manually.
#########################################
To test your install, we'll execute the log update script manually. This script is located at postgrestats/scripts/cron_log_update.php. As root, CD to the scripts directory and execute the following command from the shell (alter your path to PHP as necessary):

/usr/bin/php cron_log_update.php

On successful log-update, a shell message will be displayed: PostgreSQL Stats Log File Created/Updated. When this script is executed for the first time, a "data" directory will be created for you, located in the root level of the install directory, containing the first data file for this year/month.

First run / zeroing out the Stats:
If your Stat Collector statistics have been on but not reset for a while, the first execution of the log update script will yield much higher stats which will seem in-accurate when viewing the stats (just not a valid representation of stats for a single day / cycle). If you'd like to start out with realistic stats, simply delete the "data" folder which was created for you in the first log-update execution, and manually execute the log update script one more time.


###################################################
5. Set up the log update script as a root cron job.
###################################################
PostgreStats was designed to be executed at least once a day and preferably as close to midnight as possible. When your log-update script is executing as it should, as root, install a new crontab job which will execute the log update script for you. In the shell as root, enter cron edit mode with this command: crontab -e. Add a new crontab line which might look something like this (update your path to PHP and PostgreStats as necessary):

55 23 * * * /usr/bin/php /path/to/postgrestats/scripts/cron_log_update.php

This will execute the log update script each night at 11:55 pm. Execute this script at whatever frequency you desire. For example, if you'd feel more comfortable executing it every hour or every two hours rather than once nightly to ensure you won't lose stats if the server restarts or crashes, that might help to keep stats as accurate as possible. Healthy DB servers are not generally designed to go down easily so that's a preference on your behalf but keep in mind, if the Stat Collector statistics are reset for whatever reason (service or server restart, etc.) prior to running the log update script, those statistics in-between that time will not be captured.


######################################################################################
6. View your PostgreStats online and chown / chmod the cron log update script to root.
######################################################################################
View your PostgreStats statistics online at the web location you set-up for it previously in step 1. Click on any View link to the left and click the orange GO link to retrieve your statistics.

Once you have PostgreStats customized and running smoothly on your server, we recommend you chown and chmod the main log update PHP script (cron_log_update.php, located in the script directory of your install folder) to be owned by root with only root level privileges. To accomplish this, as root, CD to the scripts directory and issue the following two shell commands:

chown root cron_log_update.php
chmod 700 cron_log_update.php

This is just for added security and ensures that only root can access and execute the log update script.

