Package: sarg Version: 2.3.10-2 Severity: minor Dear Maintainer,
I have been trying to set up sarg and while researching solutions to my problems I came across bug 818429 (https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=818429) whose proposed fix was merged into the version this report relates to. The fix adds functionality but documentation (both within the script /usr/sbin/sarg-reports and the manpage) has not been updated and I imagine that users may not understand that only minimal configuration changes are required to make things work in a useful way. In fact it seems that the Debian package maintainers have made several changes to the sarg-reports script over time (I haven't looked at the full change log) as can be seen by comparing the distribution version with the openSUSE version of the same file (https://build.opensuse.org/package/view_file/openSUSE:Factory/sarg/sarg-reports?expand=1) which carries the same version number. I would like to propose changes to the internal documentation of the script (a patch file follows) and to the man page (changes to the text alone follow, in patch format - I don't have experience working with man pages). The revised version number is only a suggestion, of course; I assume you will determine an appropriate version number. It seems to me that fixing the documentation would go some way towards solving the problem raised in bug 369693 (https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=369693), at least as far as sarg is concerned, and especially for users of sarg-reports. --------------------------<snip><Start of patch><snip>---------------------------- --- sarg-reports +++ sarg-reports.proposed @@ -6,7 +6,7 @@ # - martijn # - Stas Degteff https://sourceforge.net/users/stas_degteff/ -VER=20050202 +VER=debian-sarg-2.3.10-2 ## What is this? # sarg-reports (this file) is a simple bash script written to automate @@ -43,11 +43,14 @@ # 30 02 1 * * sarg-reports monthly # --- END ROOT CRONTAB --- # -# REMEMBER: if you use logrotate, configure it to rotate the logs within MONTHLY basis, -# AFTER sarg-reports created the monthly html report. +# REMEMBER: if you use logrotate, configure it to retain enough logs to ensure availability +# of data for the longest period for which you need a report. +# See https://sourceforge.net/p/sarg/wiki/Keeping%20enough%20log%20to%20process/ +# This version of sarg-reports will use the log file defined in sarg.conf and also +# prior log files which have been rotated out of that location # 3) Customize the following variables: -# (Please, configure accurately the sarg.conf file before) +# (Please, configure accurately the sarg-reports.conf file before) # # (SARG) The sarg executable location # (CONFIG) The sarg main configuration file location @@ -299,6 +302,9 @@ ## HISTORY: +# debian-sarg-2.3.10-2 - use all rotated log files, pass through options from command line +# debian-sarg-? - added reports_autorm function (not used) +# ... - ? # 20050502 - Stas Degteff added support for non latin Charset and added support for OpenBSD # 20030826 - FreeBSD support (thanks to martijn to let me coding on your FreeBSD server :-)) # 20030715 - Some cleanups @@ -314,6 +320,3 @@ # doesn't like this script do: "7 days ago to yesterday" # - Monthly recognition isn't so elegant (is very ugly, i know) # - Suggestions are welcome :-) -# - If you Rotate the squid logs before sarg-reports will run, -# it will not create any html reports -# (TIPS: Rotate the logs after sarg-reports) ---------------------------<snip><End of patch><snip>----------------------------- --------------------------<snip><Start of patch><snip>---------------------------- --- sarg-reports-manpage +++ sarg-reports-manpage.proposed @@ -8,7 +8,7 @@ This manual page documents briefly the sarg-reports command. sarg-reports is a script written to automate the SARG (a powerful squid - log analyzer) reports and log management. Sarg it self, provide to end + log analyzer) reports and log management. Sarg itself, provides to end user a generic interface to create reports based on squid access log (begin of log to current date). sarg-reports is useful because it allow you to easly create and manage Daily, Weekly and Monthly reports. @@ -28,6 +28,8 @@ monthly Create Monthly report + Any further parameters supplied will be passed through to sarg. + CRONTAB If you want the reports can be generated automatically insert the following lines (the today report creation time depend mostly of your @@ -39,8 +41,12 @@ 00 01 * * 1 sarg-reports weekly 30 02 1 * * sarg-reports monthly - REMEMBER: if you use logrotate, configure it to rotate the logs within - MONTHLY basis, AFTER sarg-reports created the monthly html report. + REMEMBER: if you use logrotate, configure it to retain enough logs to + ensure availability of data for the longest period for which you need + a report. Log rotation frequency is unimportant. See + https://sourceforge.net/p/sarg/wiki/Keeping%20enough%20log%20to%20process/ + This version of sarg-reports will use the log file defined in sarg.conf + and also prior log files which have been rotated out of that location. VARIABLES Check before using the sarg-reports that the following variables are ---------------------------<snip><End of patch><snip>-----------------------------
