From: Darold Gilles Date: Tue, 21 Aug 2012 15:56:16 +0000 (+0200) Subject: Fix 0 size README X-Git-Tag: v3.2~164 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=a1afcb675d423f5f4115683f3c6852d75e9b5151;p=pgbadger Fix 0 size README --- diff --git a/README b/README index e69de29..5ffa27c 100644 --- a/README +++ b/README @@ -0,0 +1,222 @@ +ABSTRACT + pgBadger - a fast PostgreSQL log analysis report + +SYNOPSIS + pgbadger [options] logfile [...] + + PostgreSQL log analyzer with fully detailed reports and charts. + + Arguments: + + logfile can be a single log file, a list of files, or a shell command + returning a list of file. If you want to pass log content from stdin + use - as filename. + + Options: + + -a | --average minutes : number of minutes to build the average graphs of + queries and connections. + -b | --begin datetime : start date/time for the data to be parsed in log. + -d | --dbname database : only report what concern the given database + -e | --end datetime : end date/time for the data to be parsed in log. + -f | --format logtype : possible values: syslog,stderr,csv. Default: stderr + -G | --nograph : disable graphs on HTML output. Enable by default. + -h | --help : show this message and exit. + -i | --ident name : programname used as syslog ident. Default: postgres + -l | --last-parsed file: allow incremental log parsing by registering the + last datetime and line parsed. Useful if you want + to watch errors since last run or if you want one + report per day with a log rotated each week. + -m | --maxlength size : maximum length of a query, it will be cutted above + the given size. Default: no truncate + -o | --outfile filename: define the filename for the output. Default depends + of the output format: out.html or out.txt. To dump + output to stdout use - as filename. + -P | --no-prettify : disable SQL queries prettify formatter. + -q | --quiet : don't print anything to stdout, even not a progress bar. + -s | --sample number : number of query sample to store/display. Default: 3 + -t | --top number : number of query to store/display. Default: 20 + -T | --title string : change title of the HTML page report. + -u | --dbuser username : only report what concern the given user + -v | --verbose : enable verbose or debug mode. Disabled by default. + -V | --version : show pgBadger version and exit. + -w | --watch-mode : only report errors just like logwatch could do. + -x | --extension : output format. Values: text or html. Default: html + -z | --zcat exec_path : set the full path to the zcat program. Use it if + zcat is not on your path or you want to use gzcat. + --pie-limit num : pie data lower than num% will show a sum instead. + --exclude-query regex : any query matching the given regex will be excluded + from the report. For example: "^(VACUUM|COMMIT)" + you can use this option multiple time. + --exclude_file filename: path of the file which contains all the regex to use + to exclude queries from the report. One regex per line. + --disable-error : do not generate error report. + --disable-hourly : do not generate hourly reports. + --disable-type : do not generate query type report. + --disable-query : do not generate queries reports (slowest, most + frequent, ...). + --disable-session : do not generate session report. + --disable-connection : do not generate connection report. + --disable-lock : do not generate lock report. + --disable-temporary : do not generate temporary report. + --disable-checkpoint : do not generate checkpoint report. + + Examples: + + pgbadger /var/log/postgresql.log + pgbadger /var/log/postgres.log.2.gz /var/log/postgres.log.1.gz /var/log/postgres.log + pgbadger /var/log/postgresql/postgresql-2012-05-* + pgbadger --exclude-query="^(COPY|COMMIT)" /var/log/postgresql.log + pgbadger -b "2012-06-25 10:56:11" -e "2012-06-25 10:59:11" /var/log/postgresql.log + cat /var/log/postgres.log | pgbadger - + + Reporting errors every week by cron job: + + 30 23 * * 1 /usr/bin/pgbadger -q -w /var/log/postgresql.log -o /var/reports/pg_errors.html + + This suppose that your log file and HTML report are also rotated every week. + +DESCRIPTION + pgBadger is a PostgreSQL log analyzer built for speed with fully + detailed reports from your PostgreSQL log file. It's a single and small + Perl script that aims to replace and outperform the old php script + pgFouine. + + By the way, we would like to thank Guillaume Smet for all the work he + has done on this really nice tool. We've been using it a long time, it + is a really great tool! + + pgBadger is written in pure Perl language. It uses a javascript library + to draw graphs so that you don't need additional Perl modules or any + other package to install. Furthermore, this library gives us additional + features, such as zooming. + + pgBadger is able to autodetect your log file format (syslog, stderr or + csvlog). It is designed to parse huge log files, as well as gzip + compressed file. See a complete list of features below. + +FEATURE + pgBadger reports everything about your SQL queries: + + Overall statistics. + The slowest queries. + Queries that took up the most time. + The most frequent queries. + The most frequent errors. + + The following reports are also available with hourly charts: + + Hourly queries statistics. + Hourly temporary file statistics. + Hourly checkpoints statistics. + Locks statistics. + Queries by type (select/insert/update/delete). + Sessions per database/user/client. + Connections per database/user/client. + + All charts are zoomable and can be saved as PNG images. SQL queries + reported are highlighted and beautified automatically. + +REQUIREMENT + PgBadger comes as a single Perl script- you do not need anything else + than a modern Perl distribution. Charts are rendered using a Javascript + library so you don't need anything. Your browser will do all the work. + + If you planned to parse PostgreSQL CSV log files you might need some + Perl Modules: + + Text::CSV - to parse PostgreSQL CSV log files. + + This module is optional, if you don't have PostgreSQL log in the CSV + format you don't need to install it. + + Under Windows OS you may not be able to use gzipped log files unless you + have a zcat like utility that could uncompress the log file and send + content to stdout. If you have such an utility or in other OSes you want + to use other compression utility like bzip2 or Zip, use the --zcat + comand line option as follow: + + --zcat="unzip -p" or --zcat="gunzip -c" or --zcat="bzip2 -dc" + + the last example can also be used like this: --zcat="bzcat" + +POSTGRESQL CONFIGURATION + You must enable some configuration directives in your postgresql.conf + before starting. + + You must first enable SQL query logging to have something to parse: + + log_min_duration_statement = 0 + + Note that pgBadger is not compatible with statements logs provided by + log_statement and log_duration. + + With 'stderr' log format, log_line_prefix must be at least: + + log_line_prefix = '%t [%p]: [%l-1] ' + + Log line prefix could add user and database name as follows: + + log_line_prefix = '%t [%p]: [%l-1] user=%u,db=%d ' + + or for syslog log file format: + + log_line_prefix = 'user=%u,db=%d ' + + Log line prefix for stderr output could also be: + + log_line_prefix = '%t [%p]: [%l-1] db=%d,user=%u ' + + or for syslog output: + + log_line_prefix = 'db=%d,user=%u ' + + You need to enable other parameters in postgresql.conf to get more + informations from your log files: + + log_checkpoints = on + log_connections = on + log_disconnections = on + log_lock_waits = on + log_temp_files = 0 + + Do not enable log_statement and log_duration, their log format will not + be parsed by pgBadger. + + Of course your log messages should be in english without locale support: + + lc_messages='C' + + but this is not only recommanded by pgbadger. + +INSTALLATION + Download the tarball from github and unpack the archive as follow: + + tar xzf pgbadger-1.x.tar.gz + cd pgbadger-1.x/ + perl Makefile.PL + make && sudo make install + + This will copy the Perl script pgbadger in /usr/local/bin/pgbadger + directory by default and the man page into + /usr/local/share/man/man1/pgbadger.1. Those are the default installation + directory for 'site' install. + + If you want to install all under /usr/ location, use INSTALLDIRS='perl' + as argument of Makefile.PL. The script will be installed into + /usr/bin/pgbadger and the manpage into /usr/share/man/man1/pgbadger.1. + + For example, to install everything just like Debian does, proceed as + follow: + + perl Makefile.PL INSTALLDIRS=vendor + + By default INSTALLDIRS is set to site. + +AUTHORS + pgBadger is an original work from Gilles Darold. It is maintained by the + good folks at Dalibo and every one who wants to contribute. + +LICENSE + pgBadger is free software distributed under the PostgreSQL Licence. +