From 0ee30523a732bd6b98ca5b596b26abdaa9c4b285 Mon Sep 17 00:00:00 2001
From: Dylan William Hardison <dylan@hardison.net>
Date: Thu, 13 Jun 2019 15:57:07 -0400
Subject: [PATCH] docs - better documentation on logging

---
 README.rst              | 22 ++++++++++++++++++++++
 conf/log4perl-json.conf |  8 +++++++-
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/README.rst b/README.rst
index bd2a842d5..e45e7bbe4 100644
--- a/README.rst
+++ b/README.rst
@@ -411,6 +411,7 @@ LOG4PERL_CONFIG_FILE
   If the file is given as a relative path, it will belative to the /app/conf/ directory.
 
 .. _`Devel::NYTProf`: https://metacpan.org/pod/Devel::NYTProf
+
 .. _`Log::Log4perl`: https://metacpan.org/pod/Log::Log4perl
 
 LOG4PERL_STDERR_DISABLE
@@ -420,6 +421,27 @@ LOG4PERL_STDERR_DISABLE
   Note: For programs that run using the `cereal` log aggregator, this environemnt
   variable will be ignored.
 
+
+Logging Configuration
+---------------------
+
+How Bugzilla logs is entirely configured by the environmental variable
+`LOG4PERL_CONFIG_FILE`.  This config file should be familiar to someone
+familiar with log4j, and it is extensively documented in `Log::Log4perl`_.
+
+Many examples are provided in the logs/ directory.
+
+If multiple processes will need to log, it should be configured to log to a socket on port 5880.
+This will be the "cereal" daemon, which will only be started for jobqueue and httpd-type containers.
+
+The example log config files will often be configured to log to stderr
+themselves.  To prevent duplicate lines (or corrupted log messages), stderr
+logging should be filtered on the existence of the LOG4PERL_STDERR_DISABLE
+environmental variable.
+
+Logging configuration also controls which errors are sent to Sentry.
+
+
 Persistent Data Volume
 ----------------------
 
diff --git a/conf/log4perl-json.conf b/conf/log4perl-json.conf
index a9c4b6e1a..97a75e36e 100644
--- a/conf/log4perl-json.conf
+++ b/conf/log4perl-json.conf
@@ -12,13 +12,19 @@ log4perl.appender.Cereal.layout = Log::Log4perl::Layout::Mozilla
 log4perl.appender.Cereal.layout.max_json_length = 16384
 # The default is Bugzilla. This is the "Logger" field
 # in https://wiki.mozilla.org/Firefox/Services/Logging#MozLog_JSON_schema
-#and it might be useful to pass in different values for different jobs.
+# and it might be useful to pass in different values for different jobs.
 log4perl.appender.Cereal.layout.name = CEREAL
 
+# The cereal daemon ensures this env is set, so when it is set we do not need to log to stderr.
 log4perl.filter.LOG_TO_STDERR = sub { not $ENV{LOG4PERL_STDERR_DISABLE}  }
 log4perl.appender.Screen = Log::Log4perl::Appender::Screen
 log4perl.appender.Screen.Filter = LOG_TO_STDERR
+
+# change this to 0 to log to stdout
 log4perl.appender.Screen.stderr = 1
+
 log4perl.appender.Screen.layout = Log::Log4perl::Layout::Mozilla
 log4perl.appender.Screen.layout.max_json_length = 16384
+
+# This name could be something descriptive, like 'Bugzilla Fallback'
 log4perl.appender.Screen.layout.name = STDERR
-- 
2.47.3