From 4770c709c9a1a28ac2d623a7a476af15f31ecc78 Mon Sep 17 00:00:00 2001 From: Keith Wall Date: Fri, 16 May 2014 10:23:28 +0000 Subject: 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 --- .../AMQP-Messaging-Broker-Java-Book.xml | 1 + ...roker-Appendix-Operational-Logging-Messages.xml | 133 ++++++++++++++++++++- .../Java-Broker-Appendix-Queue-Alerts.xml | 101 ++++++++++++++++ .../src/java-broker/Java-Broker-Runtime-Alerts.xml | 26 ---- .../java-broker/Java-Broker-Runtime-Log-Files.xml | 53 +++++++- .../book/src/java-broker/Java-Broker-Runtime.xml | 1 - 6 files changed, 285 insertions(+), 30 deletions(-) create mode 100644 qpid/doc/book/src/java-broker/Java-Broker-Appendix-Queue-Alerts.xml delete mode 100644 qpid/doc/book/src/java-broker/Java-Broker-Runtime-Alerts.xml 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 @@ + 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 @@ - Indicates that a message store has been created. + 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. @@ -953,4 +954,134 @@ + + Transaction Store Log Messages + + + + Message Id + Message Text / Purpose + + + + + TXN-1001 + Created + + + + 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. + + + + TXN-1002 + Store location : path + + + + Indicates that the transaction store is using path for the + location of the store. + + + + TXN-1003 + Closed + + + + Indicates that the transaction store has been closed. + + + + TXN-1004 + Recovery Start + + + + Indicates that transaction recovery has begun. + + + + TXN-1005 + Recovered number messages for queue name. + + + + Indicates that recovery recovered the given number of message instances for the given queue. + + + + TXN-1006 + Recovered Complete + + + + Indicates that the message recovery is concluded. + + + + +
+ + + Configuration Store Log Messages + + + + Message Id + Message Text / Purpose + + + + + CFG-1001 + Created + + + + 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. + + + + CFG-1002 + Store location : path + + + + Indicates that the configuration store is using path for the + location of the store. + + + + CFG-1003 + Closed + + + + Indicates that the configuration store has been closed. + + + + CFG-1004 + Recovery Start + + + + Indicates that configuration recovery has begun. + + + + CFG-1005 + Recovered Complete + + + + Indicates that the configuration recovery is concluded. + + + + +
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 @@ + + +%entities; +]> + + + + Queue Alerts + 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. + For example, if queue myqueue 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. + +INFO [default:VirtualHostHouseKeepingTask] (queue.NotificationCheck) - MESSAGE_COUNT_ALERT + On Queue myqueue - 1272: Maximum count on queue threshold (1000) breached. + + Note that queue alerts are soft in nature; breaching the limit will + merely cause the alerts to be generated but messages will still be accepted to the queue. + + Queue Alerts + + + + Alert Name + Alert Format and Purpose + + + + + MESSAGE_COUNT_ALERT + MESSAGE_COUNT_ALERT On Queue queuename - + number of messages: Maximum count on queue threshold + (limit) breached. + + + + The number of messages on the given queue has breached its configured + limit. + + + + MESSAGE_SIZE_ALERT + MESSAGE_SIZE_ALERT On Queue queuename + -message size : Maximum message size threshold + (limit) breached. [Message ID=message + id] + + + + The size of an individual messages has breached its configured limit. + + + + QUEUE_DEPTH_ALERT + QUEUE_DEPTH_ALERT On Queue queuename - + total size of all messages on queue : Maximum queue depth + threshold (limit) breached. + + + + The total size of all messages on the queue has breached its configured + limit. + + + + MESSAGE_AGE_ALERT + MESSAGE_AGE_ALERT On Queue queuename - age + of message : Maximum age on queue threshold + (limit) breached. + + + + The age of a message on the given queue has breached its configured limit. + + + + +
+ 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 @@ - - - -
-Alerts - -
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 @@ -->
-Log Files - + Log Files + The Broker uses the Apache Log4J + Logging Framework for all logging activity. + In the Broker's shipped configuration, all logging is directed to log file ${QPID_WORK}/log/qpid.log. 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: + + + Opertional Log Events. These report key events in the lifecycle of objects (Broker + start-up, Queue creation, Queue deletion etc) within the Broker. See for details of the formation of these + messages. + + + Queue Alert Events. These report when the queue thresholds have been breached. See for details. + + + Any Error and Warning conditions. + + + Logging can be reconfigured either by changing the logging configuration file ${QPID_HOME}/etc/log4j.xml or at runtime using the Logging Management MBean, + see for + details. +
+ Enabling Debug + 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 org.apache.qpid from WARN to + DEBUG. + + Changing the log4j.xml configuration file to enable debug + + + +...]]> + + + Running a production system at DEBUG 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 WARN after the analysis is performed. + +
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 @@ Runtime - -- cgit v1.2.1