QPID-5554: [Java Broker Documentation] Add logging overview and appendix describing queue alerts

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1595148 13f79535-47bb-0310-9956-ffa450edef68

6 files changed, 285 insertions, 30 deletions

diff --git a/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml b/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
index 812dd851bf..83211d103a 100644
--- a/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
+++ b/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
@@ -41,4 +41,5 @@
 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-Environment-Variables.xml"/>
 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-System-Properties.xml"/>
 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-Operational-Logging-Messages.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-Queue-Alerts.xml"/>
 </book>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml b/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml
index fb4761669b..64156ce42c 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml
@@ -867,7 +867,8 @@
         </row>
         <row>
           <entry>
-            <para>Indicates that a message store has been created.</para>
+            <para>Indicates that a message store has been created.  The message store is responsible for the storage
+             of the messages themselves, including the message body and any headers.</para>
           </entry>
         </row>
         <row id="Java-Broker-Appendix-Operation-Logging-Message-MST-1002">
@@ -953,4 +954,134 @@
     </tgroup>
   </table>
 
+  <table pgwide="1" id="Java-Broker-Appendix-Operation-Logging-Message-List-TransactionStore">
+    <title>Transaction Store Log Messages</title>
+    <tgroup cols="2">
+      <thead>
+        <row>
+          <entry>Message Id</entry>
+          <entry>Message Text / Purpose</entry>
+        </row>
+      </thead>
+      <tbody>
+        <row id="Java-Broker-Appendix-Operation-Logging-Message-TXN-1001">
+          <entry morerows="1">TXN-1001</entry>
+          <entry>Created</entry>
+        </row>
+        <row>
+          <entry>
+            <para>Indicates that a transaction store has been created.  The transaction store is responsible for the storage
+              of messages instances, that is, the presence of a message on a queue.</para>
+          </entry>
+        </row>
+        <row id="Java-Broker-Appendix-Operation-Logging-Message-TXN-1002">
+          <entry morerows="1">TXN-1002</entry>
+          <entry>Store location : <replaceable>path</replaceable></entry>
+        </row>
+        <row>
+          <entry>
+            <para>Indicates that the transaction store is using <replaceable>path</replaceable> for the
+              location of the store.</para>
+          </entry>
+        </row>
+        <row id="Java-Broker-Appendix-Operation-Logging-Message-TXN-1003">
+          <entry morerows="1">TXN-1003</entry>
+          <entry>Closed</entry>
+        </row>
+        <row>
+          <entry>
+            <para>Indicates that the transaction store has been closed.</para>
+          </entry>
+        </row>
+        <row id="Java-Broker-Appendix-Operation-Logging-Message-TXN-1004">
+          <entry morerows="1">TXN-1004</entry>
+          <entry>Recovery Start</entry>
+        </row>
+        <row>
+          <entry>
+            <para>Indicates that transaction recovery has begun.</para>
+          </entry>
+        </row>
+        <row id="Java-Broker-Appendix-Operation-Logging-Message-MST-TXN">
+          <entry morerows="1">TXN-1005</entry>
+          <entry>Recovered <replaceable>number</replaceable> messages for queue <replaceable>name</replaceable>.</entry>
+        </row>
+        <row>
+          <entry>
+            <para>Indicates that recovery recovered the given number of message instances for the given queue.</para>
+          </entry>
+        </row>
+        <row id="Java-Broker-Appendix-Operation-Logging-Message-TXN-1006">
+          <entry morerows="1">TXN-1006</entry>
+          <entry>Recovered Complete</entry>
+        </row>
+        <row>
+          <entry>
+            <para>Indicates that the message recovery is concluded.</para>
+          </entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </table>
+
+  <table pgwide="1" id="Java-Broker-Appendix-Operation-Logging-Message-List-ConfigurationStore">
+    <title>Configuration Store Log Messages</title>
+    <tgroup cols="2">
+      <thead>
+        <row>
+          <entry>Message Id</entry>
+          <entry>Message Text / Purpose</entry>
+        </row>
+      </thead>
+      <tbody>
+        <row id="Java-Broker-Appendix-Operation-Logging-Message-CFG-1001">
+          <entry morerows="1">CFG-1001</entry>
+          <entry>Created</entry>
+        </row>
+        <row>
+          <entry>
+            <para>Indicates that a configuration store has been created.  The configuration store is responsible
+              for the storage of the definition of objects such as queues, exchanges, and bindings.</para>
+          </entry>
+        </row>
+        <row id="Java-Broker-Appendix-Operation-Logging-Message-CFG-1002">
+          <entry morerows="1">CFG-1002</entry>
+          <entry>Store location : <replaceable>path</replaceable></entry>
+        </row>
+        <row>
+          <entry>
+            <para>Indicates that the configuration store is using <replaceable>path</replaceable> for the
+              location of the store.</para>
+          </entry>
+        </row>
+        <row id="Java-Broker-Appendix-Operation-Logging-Message-CFG-1003">
+          <entry morerows="1">CFG-1003</entry>
+          <entry>Closed</entry>
+        </row>
+        <row>
+          <entry>
+            <para>Indicates that the configuration store has been closed.</para>
+          </entry>
+        </row>
+        <row id="Java-Broker-Appendix-Operation-Logging-Message-CFG-1004">
+          <entry morerows="1">CFG-1004</entry>
+          <entry>Recovery Start</entry>
+        </row>
+        <row>
+          <entry>
+            <para>Indicates that configuration recovery has begun.</para>
+          </entry>
+        </row>
+        <row id="Java-Broker-Appendix-Operation-Logging-Message-CFG-1005">
+          <entry morerows="1">CFG-1005</entry>
+          <entry>Recovered Complete</entry>
+        </row>
+        <row>
+          <entry>
+            <para>Indicates that the configuration recovery is concluded.</para>
+          </entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </table>
 </appendix>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Queue-Alerts.xml b/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Queue-Alerts.xml
new file mode 100644
index 0000000000..687a063289
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Queue-Alerts.xml
@@ -0,0 +1,101 @@
+<?xml version="1.0"?>
+<!DOCTYPE entities [
+<!ENTITY %  entities SYSTEM  "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+<appendix id="Java-Broker-Appendix-Queue-Alerts">
+  <title>Queue Alerts</title>
+  <para>The Broker supports a variety of queue alerting thresholds. Once configured on a queue,
+    these limits will be periodically written to the log if these limits are breached, until the
+    condition is rectified.</para>
+  <para>For example, if queue <literal>myqueue</literal> is configured with a message count alert of
+    1000, and then owing to a failure of a downstream system messages begin to accumulate on the
+    queue, the following alerts will be written periodically to the log. </para>
+  <screen>
+INFO [default:VirtualHostHouseKeepingTask] (queue.NotificationCheck) - MESSAGE_COUNT_ALERT
+           On Queue myqueue - 1272: Maximum count on queue threshold (1000) breached.
+  </screen>
+  <para>Note that queue alerts are <emphasis>soft</emphasis> in nature; breaching the limit will
+    merely cause the alerts to be generated but messages will still be accepted to the queue.</para>
+  <table pgwide="1" id="Java-Broker-Appendix-Queue-Alerts-Alerting-Messages">
+    <title>Queue Alerts</title>
+    <tgroup cols="2">
+      <thead>
+        <row>
+          <entry>Alert Name</entry>
+          <entry>Alert Format and Purpose</entry>
+        </row>
+      </thead>
+      <tbody>
+        <row>
+          <entry morerows="1">MESSAGE_COUNT_ALERT</entry>
+          <entry> MESSAGE_COUNT_ALERT On Queue <replaceable>queuename</replaceable> -
+              <replaceable>number of messages</replaceable>: Maximum count on queue threshold
+              (<replaceable>limit</replaceable>) breached. </entry>
+        </row>
+        <row>
+          <entry>
+            <para>The number of messages on the given queue has breached its configured
+              limit.</para>
+          </entry>
+        </row>
+        <row>
+          <entry morerows="1">MESSAGE_SIZE_ALERT</entry>
+          <entry> MESSAGE_SIZE_ALERT On Queue <replaceable>queuename</replaceable>
+              -<replaceable>message size</replaceable> : Maximum message size threshold
+              (<replaceable>limit</replaceable>) breached. [Message ID=<replaceable>message
+              id</replaceable>]</entry>
+        </row>
+        <row>
+          <entry>
+            <para>The size of an individual messages has breached its configured limit.</para>
+          </entry>
+        </row>
+        <row>
+          <entry morerows="1">QUEUE_DEPTH_ALERT</entry>
+          <entry> QUEUE_DEPTH_ALERT On Queue <replaceable>queuename</replaceable> -
+              <replaceable>total size of all messages on queue</replaceable> : Maximum queue depth
+            threshold (<replaceable>limit</replaceable>) breached.</entry>
+        </row>
+        <row>
+          <entry>
+            <para>The total size of all messages on the queue has breached its configured
+              limit.</para>
+          </entry>
+        </row>
+        <row>
+          <entry morerows="1">MESSAGE_AGE_ALERT</entry>
+          <entry>MESSAGE_AGE_ALERT On Queue <replaceable>queuename</replaceable> - <replaceable>age
+              of message</replaceable> : Maximum age on queue threshold
+              (<replaceable>limit</replaceable>) breached. </entry>
+        </row>
+        <row>
+          <entry>
+            <para>The age of a message on the given queue has breached its configured limit.</para>
+          </entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </table>
+</appendix>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Alerts.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Alerts.xml
deleted file mode 100644
index 29ac68b937..0000000000
--- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Alerts.xml
+++ /dev/null
@@ -1,26 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!--
-
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements.  See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership.  The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License.  You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied.  See the License for the
- specific language governing permissions and limitations
- under the License.
-
--->
-
-<section id="Java-Broker-Runtime-Alerts">
-<title>Alerts</title>
-
-</section>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml
index 84ee4db6d3..dc5a5b510d 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml
@@ -21,6 +21,55 @@
 -->
 
 <section id="Java-Broker-Runtime-Log-Files">
-<title>Log Files</title>
-
+ <title>Log Files</title>
+ <para> The Broker uses the <ulink href="http://logging.apache.org/log4j/1.2/">Apache Log4J</ulink>
+  Logging Framework for all logging activity. </para>
+ <para> In the Broker's shipped configuration, all logging is directed to log file <literal><link
+    linkend="Java-Broker-Appendix-Environment-Variables-Qpid-Work"
+   >${QPID_WORK}</link>/log/qpid.log</literal>. The log file is not rotated and will be overwritten
+  when the Broker restarts. Logging levels are configured in such a way that the log will comprise
+  of:</para>
+ <itemizedlist>
+  <listitem>
+   <para>Opertional Log Events. These report key events in the lifecycle of objects (Broker
+    start-up, Queue creation, Queue deletion etc) within the Broker. See <xref
+     linkend="Java-Broker-Appendix-Operation-Logging"/> for details of the formation of these
+    messages.</para>
+  </listitem>
+  <listitem>
+   <para>Queue Alert Events. These report when the queue thresholds have been breached. See <xref
+    linkend="Java-Broker-Appendix-Queue-Alerts"/> for details.</para>
+  </listitem>
+  <listitem>
+   <para>Any Error and Warning conditions.</para>
+  </listitem>
+ </itemizedlist>
+ <para>Logging can be reconfigured either by changing the logging configuration file <literal><link
+    linkend="Java-Broker-Appendix-Environment-Variables-Qpid-Home"
+   >${QPID_HOME}</link>/etc/log4j.xml</literal> or at runtime using the Logging Management MBean,
+  see <xref linkend="Java-Broker-Configuring-And-Managing-JMX-Management-MBeans"/> for
+  details.</para>
+ <section id="Java-Broker-Runtime-Log-Files-Enable-Debug">
+  <title>Enabling Debug</title>
+  <para>It can be helpful to enable debug within the Broker in order to understand a problem more
+   clearly. If this is required, debug can be enabled at runtime (without restarting the Broker)
+   using the Logging Management MBean. The change can also be made by changing the log configuration
+   file and restarting the Broker. Whichever mechanism is chosen, change the appender assoicated
+   with <literal>org.apache.qpid</literal> from <literal>WARN</literal> to
+   <literal>DEBUG</literal>.</para>
+  <example>
+   <title>Changing the log4j.xml configuration file to enable debug</title>
+   <screen><![CDATA[
+...
+<logger additivity="true" name="org.apache.qpid">
+    <level value="debug"/> <!-- change the level value from warn to debug -->
+</logger>
+...]]></screen>
+  </example>
+  <important>
+   <para>Running a production system at <literal>DEBUG</literal> level can have performance
+    implications by slowing the Broker down. It can also generate large log files. Take care to
+    revert the logging level back to <literal>WARN</literal> after the analysis is performed.</para>
+  </important>
+ </section>
 </section>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml
index 3c2b9b8dcc..6eaa6a1ca0 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml
@@ -23,7 +23,6 @@
 <chapter id="Java-Broker-Runtime">
   <title>Runtime</title>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Runtime-Log-Files.xml"/>
-        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Runtime-Alerts.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Runtime-Disk-Space-Management.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Runtime-Producer-Transaction-Timeout.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Runtime-Handling-Undeliverable-Messages.xml"/>