7.0-Logs.md

@@ -0,0 +1,22 @@
+# the log file
+
+This script creates a very detailed log file listing all actions: processes, successes, warnings, errors. Everything is timestamped so you can track if any one process is taking too much time or otherwise track down errors that you may encounter. The log file also includes the locations of all temp files created and if there were any errors removing those files. Finally, it also lists where it's looking for things such as external configuration files, a 503-error page, etc. This helps you figure out if there is a bug in the script or if you just supplied an incorrect parameter value.
+
+The log file is colour-coded to make it easier for you to review and quickly see warnings/errors. This does, however, mean that using programs like nano or vi may be difficult since they display the ANSI colour codes instead of displaying the colours. Thus, I'd recommend using simplier commands like `cat backup.log | more` or `tail -n numberOfLines backup.log` to view your logs. You can also grep them to search them, but be aware that the ANSI codes might impact how you need to search via grep.
+
+All script messages are prepended with a type such as [INFO], [WARNING] or [ERROR] to make visually searching it easier and to allow log-parsing programs to summarize the messages. In fact, if you are using *logwatch* as your log-parsing program, then I've done the work for you!
+
+## log rotation
+
+The log file generated by this script is fairly detailed so it can grow quite large over time. This is especially true if you are using verbose output from borg for any troubleshooting or for compliance/auditing. I've included a sample commented logrotate config file in this git archive at */etc/logrotate.d* which you can modify and drop into that same directory on your Debian/Ubuntu system. If you are using another log rotating solution, then please remember to configure it so that your log files don't get overwhelmingly large should you need to parse them if something goes wrong with your backups.
+
+## logwatch overview
+
+The following pages in this wiki will go over the integration with logwatch in greater detail, but here's a quick summary that should get you going. Log-group, conf and service files are included in this repo to get you going quickly and without needing to program anything. The reporting detail levels are as follows:
+
+* 0: Summary of total successes, warnings and errors ONLY
+* 1-4: Actual success, warning and error messages displayed. Levels 1-4 are all the same.
+* 5: Same as levels 1-4 but also includes info messages.
+* 6+: Dumps the entire raw log file including any debugging messages. All levels 6 and above are the same.
+
+Please review the wiki pages in section 7 for more information. If you don't really care how it all works, then just copy the files from the */etc/logwatch* directory of this repo to your */etc/logwatch* directory. The paths are already correct for a default logwatch install on Debian/Ubuntu. You will, however, need to update the log-group file to reflect the path to the script's log file.