Author: kwall
Date: Fri May 16 10:23:28 2014
New Revision: 1595148
URL: http://svn.apache.org/r1595148
Log:
QPID-5554: [Java Broker Documentation] Add logging overview and appendix
describing queue alerts
Added:
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Queue-Alerts.xml
Removed:
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Alerts.xml
Modified:
qpid/trunk/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml
Modified:
qpid/trunk/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml?rev=1595148&r1=1595147&r2=1595148&view=diff
==============================================================================
---
qpid/trunk/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
(original)
+++
qpid/trunk/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
Fri May 16 10:23:28 2014
@@ -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>
Modified:
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml?rev=1595148&r1=1595147&r2=1595148&view=diff
==============================================================================
---
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml
(original)
+++
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml
Fri May 16 10:23:28 2014
@@ -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>
Added:
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Queue-Alerts.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Queue-Alerts.xml?rev=1595148&view=auto
==============================================================================
---
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Queue-Alerts.xml
(added)
+++
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Queue-Alerts.xml
Fri May 16 10:23:28 2014
@@ -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>
Modified:
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml?rev=1595148&r1=1595147&r2=1595148&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml
(original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml
Fri May 16 10:23:28 2014
@@ -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>
Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml?rev=1595148&r1=1595147&r2=1595148&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml Fri May 16
10:23:28 2014
@@ -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"/>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
