From 81ac902d6dd0ca4e5413a1aa6d625a71a44fc210 Mon Sep 17 00:00:00 2001 From: Keith Wall Date: Sat, 1 Mar 2014 01:49:40 +0000 Subject: QPID-5554: [Java Broker Documentation] Add docbook chapters for environment variables, system properties and operational logging git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1573121 13f79535-47bb-0310-9956-ffa450edef68 --- .../AMQP-Messaging-Broker-Java-Book.xml | 4 +- .../Java-Broker-Appendix-Environment-Variables.xml | 126 +++ ...roker-Appendix-Operational-Logging-Messages.xml | 956 +++++++++++++++++++++ .../Java-Broker-Appendix-System-Properties.xml | 172 ++++ .../src/java-broker/Java-Broker-Installation.xml | 4 +- 5 files changed, 1259 insertions(+), 3 deletions(-) create mode 100644 qpid/doc/book/src/java-broker/Java-Broker-Appendix-Environment-Variables.xml create mode 100644 qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml create mode 100644 qpid/doc/book/src/java-broker/Java-Broker-Appendix-System-Properties.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 2beb77d965..812dd851bf 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 @@ -38,5 +38,7 @@ - + + + diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Environment-Variables.xml b/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Environment-Variables.xml new file mode 100644 index 0000000000..eea7bb6b79 --- /dev/null +++ b/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Environment-Variables.xml @@ -0,0 +1,126 @@ + + +%entities; +]> + + + + Environment Variables + The following table describes the environment variables understood by the Qpid scripts + contained within the /bin directory within the Broker distribution. + To take effect, these variables must be set within the shell (and exported - if using Unix) + before invoking the script. + + Environment variables + + + + Environment variable + Default + Purpose + + + + + QPID_HOME + + None + + + The variable used to tell the Broker its installation directory. It must be an + absolute path. This is used to determine the location of Qpid's dependency JARs and + some configuration files. + Typically the value of this variable will look similar to + c:\qpid\&windowsExtractedBrokerDirName; (Windows) or + /usr/local/qpid/&unixExtractedBrokerDirName; (Unix). The + installation prefix will differ from installation to installation. + If not set, a value for QPID_HOME is derived from the location + of the script itself. + + + + QPID_WORK + + User's home directory + + + Used as the default root directory for any data written by the Broker. This is the + default location for any message data written to persistent stores and the Broker's + log file. + For example, QPID_WORK=/var/qpidwork. + + + + QPID_OPTS + + None + + + This is the preferred mechanism for passing Java system properties to the + Broker. The value must be a list of system properties each separate by a space. + -Dname1=value1 + -Dname2=value2. + + + + + QPID_JAVA_GC + + -XX:+HeapDumpOnOutOfMemoryError -XX:+UseConcMarkSweepGC + + + This is the preferred mechanism for customising garbage collection behaviour. The + value should contain valid garbage collection options(s) for the target JVM. + Refer to the JVM's documentation for details. + + + + QPID_JAVA_MEM + + -Xmx1024m + + + This is the preferred mechanism for customising the size of the JVM's heap memory. + The value should contain valid memory option(s) for the target JVM. Oracle JVMs + understand -Xmx to specify a maximum heap size and + -Xms an initial size. + For example, QPID_JAVA_MEM=-Xmx6g would set a maximum heap size of + 6GB. + Refer to the JVM's documentation for details. + + + + JAVA_OPTS + None + + This is the preferred mechanism for passing any other JVM options. This variable is + commonly used to pass options for diagnostic purposes, for instance to turn on verbose + GC. -verbose:gc. + Refer to the JVM's documentation for details. + + + + +
+ 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 new file mode 100644 index 0000000000..f169faccfc --- /dev/null +++ b/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml @@ -0,0 +1,956 @@ + + +%entities; +]> + + + + Operational Logging + The Broker will, by default, produce structured log messages in response to key events in + the lives of objects within the Broker. These consise messages are designed to allow the user to + understand the actions of the Broker in retrospect. This is valuable for problem diagnosis and + provides a useful audit trail. + Each log message includes details of the entity causing the action (e.g. a management user + or messaging client connection), the entity receiving the action (e.g. a queue or connection) + and a description of operation itself. + The log messages have the following format: + + [Actor] {[Subject]} [Message Id] [Message Text] + + Where: + + + Actor is the entity within the Broker that is + performing the action. There are actors corresponding to the Broker + itself, Management, Connection, and Channels. Their format is described in the table below. + + + Subject (optional) is the entity within the Broker that is + receiving the action. There are subjects corresponding to the + Connections, Channels, Queues, Exchanges, Subscriptions, and Message Stores. Their format is + described in the table below. + Some actions are reflexive, in these cases the Actor and Subject will be equal. + + + Message Id is an identifier for the type of message. It has the form + three alphas and four digits separated by a hyphen AAA-9999. + + + Message Text is a textual description + + + To illustrate, let's look at two examples. + CON-1001 is used when a messages client makes an AMQP connection. The + connection actor (con) provides us with details of the peer's connection: the + user id used by the client (myapp1), their IP, ephemeral port number and the name of the virtual + host. The message text itself gives us further details about the connection: the client id, the + protocol version in used, and details of the client's qpid library. + [con:8(myapp1@/127.0.0.1:52851/default)] CON-1001 : Open : Client ID : clientid : + Protocol Version : 0-10 : Client Version : &qpidCurrentRelease; : Client Product : qpid + QUE-1001 is used when a queue is created. The connection actor + con tells us details of the connection performing the queue creation: the + user id used by the client (myapp1), the IP, ephemeral port number and the name of the virtual + host. The queue subject tells use the queue's name (myqueue) and the virtualhost. The message + itself tells us more information about the queue that is being created. + + [con:8(myapp1@/127.0.0.1:52851/default)/ch:0] [vh(/default)/qu(myqueue)] QUE-1001 : Create : Owner: clientid Transient + The first two tables that follow describe the actor and subject entities, then the later + provide a complete catalogue of all supported messages. + + Actors Entities + + + + Actor Type + Format and Purpose + + + + + Broker + [Broker] + + + + Used during startup and shutdown + + + + Management + + [mng:userid(clientip:ephemeralport)] + + + + + Used for operations performed by the either the JMX or Web Management + interfaces. + + + + Connection + + [con:connectionnumber(userid@/clientip:ephemeralport/virtualhostname)] + + + + Used for operations performed by a client connection. Note that connections are + numbered by a sequence number that begins at 1. + + + + Channel + + [con:connectionnumber(userid@/clientip:ephemeralport/virtualhostname/ch:channelnumber)] + + + + Used for operations performed by a client's channel (corresponds to the JMS + concept of Session). Note that channels are numbered by a sequence number that is + scoped by the owning connection. + + + + +
+ + Subject Entities + + + + Subject Type + Format and Purpose + + + + + Connection + + [con:connectionnumber(userid@/clientip:ephemeralport/virtualhostname)] + + + + A connection to the Broker. + + + + Channel + + [con:connectionnumber(userid@/clientip:ephemeralport/virtualhostname/ch:channelnumber)] + + + + A client's channel within a connection. + + + + Subscription + + [sub:subscriptionnumber(vh(/virtualhostname)/qu(queuename)] + + + + A subscription to a queue. This corresponds to the JMS concept of a + Consumer. + + + + Queue + [vh(/virtualhostname)/qu(queuename)] + + + + A queue on a virtualhost + + + + Exchange + [vh(/virtualhostname)/ex(exchangetype/exchangename)] + + + + An exchange on a virtualhost + + + + Binding + + [vh(/virtualhostname)/ex(exchangetype/exchangename)/qu(queuename)/rk(bindingkey)] + + + + A binding between a queue and exchange with the giving binding key. + + + + Message Store + + [vh(/virtualhostname)/ms(messagestorename)] + + + + A virtualhost/message store on the Broker. + + + + +
+ The following tables lists all the operation log messages that can be produced by the + Broker, and the describes the circumstances under which each may be seen. + + + Broker Log Messages + + + + Message Id + Message Text / Purpose + + + + + BRK-1001 + Startup : Version: version Build: + build + + + + + Indicates that the Broker is starting up + + + + BRK-1002 + Starting : Listening on transporttype port + portnumber + + + + + Indicates that the Broker has begun listening on a port. + + + + BRK-1003 + Shutting down : transporttype port + portnumber + + + + + Indicates that the Broker has stopped listening on a port. + + + + BRK-1004 + Qpid Broker Ready + + + + Indicates that the Broker is ready for normal operations. + + + + BRK-1005 + Stopped + + + + Indicates that the Broker is stopped. + + + + BRK-1006 + Using configuration : file + + + + + Indicates the name of the configuration store in use by the Broker. + + + + BRK-1007 + Using logging configuration : file + + + + + Indicates the name of the log configuration file in use by the Broker. + + + + BRK-1008 + delivered|received : size + kB/s peak : size bytes total + + + + Statistic - bytes delivered or received by the Broker. + + + + BRK-1009 + delivered|received : size + msg/s peak : size msgs total + + + + Statistic - messages delivered or received by the Broker. + + + + +
+ + + Management Log Messages + + + + Message Id + Message Text / Purpose + + + + + MNG-1001 + type Management Startup + + + + Indicates that a Management plugin is starting up. Currently supported management + plugins are JMX and Web. + + + + MNG-1002 + Starting : type : Listening on port + port + + + + + Indicates that a Management plugin is listening on the given port. + + + + MNG-1003 + Shutting down : type : port + port + + + + Indicates that a Management plugin is ceasing to listen on the given port. + + + + MNG-1004 + type Management Ready + + + + Indicates that a Management plugin is ready for work. + + + + MNG-1005 + type Management Stopped + + + + Indicates that a Management plugin is stopped. + + + + MNG-1006 + Using SSL Keystore : file + + + + Indicates that a Management transport is secured by SSL and using the given + keystore file. + + + + MNG-1007 + Open : User username + + + + Indicates the opening of a connection to Management has by the given + username. + + + + MNG-1008 + Close : User username + + + + Indicates the closing of a connection to Management has by the given + username. + + + + +
+ + + Virtual Host Log Messages + + + + Message Id + Message Text / Purpose + + + + + + VHT-1001 + Created : virtualhostname + + + + Indicates that a virtualhost has been created. + + + + VHT-1002 + Closed + + + + Indicates that a virtualhost has been closed. This occurs on Broker + shutdown. + + + + VHT-1003 + virtualhostname : + delivered|received : size kB/s + peak : size bytes total + + + + Statistic - bytes delivered or received by the virtualhost. + + + + VHT-1004 + virtualhostname : + delivered|received : size msg/s + peak : size msgs total + + + + Statistic - messages delivered or received by the virtualhost. + + + + VHT-1005 + Unexpected fatal error + + + + Virtualhost has suffered an unexpected fatal error, check the logs for more + details. + + + + +
+ + Queue Log Messages + + + + Message Id + Message Text / Purpose + + + + + + QUE-1001 + Create : Owner: owner + AutoDelete [Durable] + Transient Priority: + numberofpriorities + + + + Indicates that a queue has been created. + + + + QUE-1002 + Deleted + + + + Indicates that a queue has been deleted. + + + + QUE-1003 + Overfull : Size : size bytes, Capacity : + maximumsize + + + + Indicates that a queue has exceeded its permitted capacity. See for details. + + + + QUE-1004 + Underfull : Size : size bytes, Resume Capacity : + resumesize + + + + Indicates that a queue has fallen to its resume capacity. See for details. + + + + +
+ + Exchange Log Messages + + + + Message Id + Message Text / Purpose + + + + + + EXH-1001 + Create : [Durable] Type: type + Name: exchange name + + + + Indicates that an exchange has been created. + + + + EXH-1002 + Deleted + + + + Indicates that an exchange has been deleted. + + + + EXH-1003 + Discarded Message : Name: exchange name Routing Key: + routing key + + + + Indicates that an exchange received a message that could not be routed to at least + one queue. queue has exceeded its permitted capacity. See for details. + + + + +
+ + + Binding Log Messages + + + + Message Id + Message Text / Purpose + + + + + BND-1001 + Create : Arguments : arguments + + + + Indicates that a binding has been made between an exchange and a queue. + + + + BND-1002 + Deleted + + + + Indicates that a binding has been deleted + + + + + +
+ + + Connection Log Messages + + + + Message Id + Message Text / Purpose + + + + + CHN-1001 + Open : Client ID : clientid : Protocol Version : + protocol version : Client Version : client + version : Client Product :client + product + + + + Indicates that a connection has been opened. The Broker logs one of these message + each time it learns more about the client as the connection is negotiated. + + + + CHN-1002 + Close + + + + Indicates that a connection has been closed. This message is logged regardless of + if the connection is closed normally, or if the connection is somehow lost e.g network + error. + + + + CHN-1003 + Closed due to inactivity + + + + Used when heart beating is in-use. Indicates that the connection has not received + a heartbeat for too long and is therefore closed as being inactive. + + + + +
+ + + + Channel Log Messages + + + + Message Id + Message Text / Purpose + + + + + CHN-1001 + Create + + + + Indicates that a channel (corresponds to the JMS concept of Session) has been + created. + + + + CHN-1002 + Flow Started + + + + Indicates message flow to a session has begun. + + + + CHN-1003 + Close + + + + Indicates that a channel has been closed. + + + + CHN-1004 + Prefetch Size (bytes) size : Count number + of messages + + + + Indicates the prefetch size in use by a channel. + + + + CHN-1005 + Flow Control Enforced (Queue queue name) + + + + Indicates that producer flow control has been imposed on a channel owning to + excessive queue depth in the indicated queue. Produces using the channel will be + requested to pause the sending of messages. See for more details. + + + + CHN-1006 + Flow Control Removed + + + + Indicates that producer flow control has been removed from a channel. See for more details. + + + + CHN-1007 + Open Transaction : time ms + + + + Indicates that a producer transaction has been open for longer than that + permitted. See for + more details. + + + + CHN-1008 + Idle Transaction : time ms + + + + Indicates that a producer transaction has been idle for longer than that + permitted. See for + more details. + + + + CHN-1009 + Discarded message : message number as no alternate + exchange configured for queue : queue name{1} routing key : + routing key + + + + Indicates that a channel has discarded a message as the maximum delivery count has + been exceeded but the queue defines no alternate exchange. See for more details. Note that message number is an + internal message reference. + + + + CHN-1010 + Discarded message : message number as no binding on + alternate exchange : exchange name + + + + Indicates that a channel has discarded a message as the maximum delivery count has + been exceeded but the queue's alternate exchange has no binding to a queue. See for more details. Note that message number is an + internal message reference. + + + + CHN-1011 + Message : message number moved to dead letter queue : + queue name + + + + Indicates that a channel has moved a message to the named dead letter queue + + + + + +
+ + Subscription Log Messages + + + + Message Id + Message Text / Purpose + + + + + SUB-1001 + Create : [Durable] Arguments : + arguments + + + + Indicates that a subscription (corresponds to JMS concept of a MessageConsumer) + has been created. + + + + SUB-1002 + Close + + + + Indicates that a subscription has been closed. + + + + SUB-1003 + State : boolean + + + + Indicates that a subscription has changed state. This occurs when the consumer is + ready to receive more messages. As this happens frequently in normal operation, this + log messages is disabled by default. + + + + + +
+ + + Message Store Log Messages + + + + Message Id + Message Text / Purpose + + + + + MST-1001 + Created + + + + Indicates that a message store has been created. + + + + MST-1002 + Store location : path + + + + Indicates that the message store is using path for the + location of the message store. + + + + MST-1003 + Closed + + + + Indicates that the message store has been closed. + + + + MST-1004 + Recovery Start + + + + Indicates that message recovery has begun. + + + + MST-1005 + Recovered number of messages messages. + + + + Indicates that recovery recovered the given number of messages from the + store. + + + + MST-1006 + Recovered Complete + + + + Indicates that the message recovery is concluded. + + + + MST-1007 + Store Passivated + + + + The store is entering a passive state where is it unavailable for normal + operations. Currently this message is used by HA when the node is in replica + state. + + + + MST-1008 + Store overfull, flow control will be enforced + + + + The store has breached is maximum configured size. See for details. + + + + MST-1009 + Store overfull condition cleared + + + + The store size has fallen beneath its resume capacity and therefore flow control + has been rescinded. See for + details. + + + + +
+ + diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Appendix-System-Properties.xml b/qpid/doc/book/src/java-broker/Java-Broker-Appendix-System-Properties.xml new file mode 100644 index 0000000000..0c71c17c71 --- /dev/null +++ b/qpid/doc/book/src/java-broker/Java-Broker-Appendix-System-Properties.xml @@ -0,0 +1,172 @@ + + +%entities; +]> + + + + System Properties + The following table describes the Java system properties used by the Broker to control + various optional behaviours. + The preferred method of enabling these system properties is using the QPID_OPTS environment variable described in the previous + section. + + System properties + + + + System property + Default + Purpose + + + + + qpid.shared_msg_group + + qpid.no-group + + + Controls the default group for groups operating in 'shared groups' mode. See + + + + qpid.broker_heartbeat_timeout_factor + 2 + Factor to determine the maximum length of that may elapse between heartbeats being + received from the peer before a connection is deemed to have been broken. + + + qpid.broker_dead_letter_exchange_suffix + _DLE + Used with the + feature. Governs the suffix used when generating a name for a Dead Letter + Exchange. + + + qpid.broker_dead_letter_queue_suffix + _DLQ + Used with the + feature. Governs the suffix used when generating a name for a Dead Letter Queue. + + + qpid.broker_msg_auth + false + + If set true, the Broker ensures that the user id of each received message matches + the user id of the producing connection. If this check fails, the message is returned + to the producer's connection with a 403 (Access Refused) error code. + This is check is currently not enforced when using AMQP 0-10 and 1-0 + protocols. + + + + qpid.broker_status_updates + true + + If set true, the Broker will produce operational logging messages. + + + + qpid.broker_default_amqp_protocol_excludes + none + + Controls the AMQP protocol versions supported by the Broker. The value of this + property is a comma separated list of AMQP protocol versions whose support should be + disabled. + + + + qpid.broker_default_amqp_protocol_includes + none + + Controls the AMQP protocol versions supported by the Broker. The value of this + property is a comma separated list of AMQP protocol versions whose support should be + enabled. + + + + qpid.broker_default_supported_protocol_version_reply + none + + Used during protocol negotiation. If set, the Broker will offer this AMQP version + to a client requesting an AMQP protocol that is not supported by the Broker. If not set, the + Broker offers the highest protocol version it supports. + + + + qpid.broker_disabled_features + none + + Allows optional Broker features to be disabled. Currently understood feature + names are: qpid.jms-selector + Feature names should be comma separated. + + + + qpid.broker_frame_size + 65536 + + Maximum AMQP frame size supported by the Broker. + + + + qpid.broker_jmx_method_rights_infer_all_access + true + + Used when using ACLs and the JMX + management interface. + If set true, the METHOD object permission is sufficient to allow the user to + perform the operation. If set false, the user will require both the METHOD object + permission and the underlying object permission too (for instance QUEUE object + permission if performing management operations on a queue). If the user is not granted + both permissions, the operation will be denied. + + + + qpid.broker_jmx_use_custom_rmi_socket_factory + true + + Applicable to the JMX management interface. If true, the Broker creates a custom + RMI socket factory that is secured from changes outside of the JVM. If false, + a standard RMI socket factory is used. + It is not recommended to change this property from its default value. + + + + qpid.broker_log_records_buffer_size + 4096 + + Controls the number of recent Broker log entries that remain viewable online via + the HTTP Management interface. + + + + +
+ diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml b/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml index 7e694372c8..822caaad4a 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml @@ -125,7 +125,7 @@ command-line (for the lifetime of the command interpreter), but you will normally want to set the environment variable permanently via the Advanced System Settings in the Control Panel. set QPID_WORK=C:\qpidwork - If the directory referred to by QPID_WORK does not exist, the Java Broker will attempt to create it + If the directory referred to by QPID_WORK does not exist, the Java Broker will attempt to create it on start-up.
@@ -169,7 +169,7 @@ drwxr-xr-x 34 qpid qpid 1156 25 Jul 23:22 lib the environment variable permanently the user's shell profile file (~/.bash_profile for Bash etc). - If the directory referred to by QPID_WORK does not exist, the Java Broker will attempt to create it + If the directory referred to by QPID_WORK does not exist, the Java Broker will attempt to create it on start-up.
-- cgit v1.2.1