You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by kw...@apache.org on 2015/10/22 12:34:39 UTC
svn commit: r1709983 - in /qpid/java/trunk/doc/book/src/java-broker: ./
concepts/ management/channels/
Author: kwall
Date: Thu Oct 22 10:34:38 2015
New Revision: 1709983
URL: http://svn.apache.org/viewvc?rev=1709983&view=rev
Log:
QPID-6801: [Java Broker] Logging documentation. Incorporate review comments from Lorenz Quack <lq...@apache.org>
Modified:
qpid/java/trunk/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml
qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml
qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml
qpid/java/trunk/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml
Modified: qpid/java/trunk/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml?rev=1709983&r1=1709982&r2=1709983&view=diff
==============================================================================
--- qpid/java/trunk/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml (original)
+++ qpid/java/trunk/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml Thu Oct 22 10:34:38 2015
@@ -48,7 +48,7 @@
</para>
<para>In the remainder of this section you will first find a description of the concepts used in
the logging subsystem. Next, you find a description of the default configuration. The section
- then concludes with a in-depth description of the loggers themselves and how they many be
+ then concludes with a in-depth description of the loggers themselves and how they may be
configured.</para>
<section id="Java-Broker-Runtime-Logging-Concepts">
<title>Concepts</title>
@@ -64,7 +64,7 @@
<para>Loggers are attached at two points within the Broker Model; the Broker itself and
the virtualhosts. Loggers attached at the Broker can capture log events for the system
as a whole, or can exclude events related to virtualhosts.</para>
- <para>Loggers attached to a Virtualhost capture log events relating to that virtualhost
+ <para>Loggers attached to a virtualhost capture log events relating to that virtualhost
only.</para>
<para>The Broker and virtualhosts can have zero or more Loggers. If no loggers are
configured, no logging is generated at all.</para>
@@ -101,9 +101,8 @@
<literal>${QPID_WORK}/log/qpid.log</literal>.</para>
</listitem>
<listitem>
- <para>The Broker also caches the last 4096 log events in a memory cache. The log contains:
- all operational logging events, and events from Qpid itself that are deemed
- informational or higher.</para>
+ <para>The Broker also caches the last 4096 log events in a memory cache. By default, the
+ memory logger logs the same things the file logger does.</para>
</listitem>
</itemizedlist>
</para>
@@ -115,17 +114,17 @@
</section>
<section id="Java-Broker-Runtime-Logging-Loggers">
<title>Loggers</title>
- <para>Loggers are responsible for the writing a log. The log includes log events that match a
+ <para>Loggers are responsible for the writing of a log. The log includes log events that match a
Logger's inclusion rules.</para>
- <para>Loggers are associated with either the Broker or a Virtualhost. Virtualhost loggers write
+ <para>Loggers are associated with either the Broker or a virtualhost. Virtualhost loggers write
only log events related to that virtualhost. Broker Loggers write log events from the Broker
as a whole. Optionally a Broker Logger can be configured to exclude log events coming from
- Virtualhosts. These abilities can be useful exploited together in managed service
- scenarios.</para>
- <para>Loggers can be added or removed, or inclusion rules added, removed or changed, at runtime
- without restarting the Broker, but changes to configuration of a Logger such as filenames and
- rolling options don't take effect until next restart.</para>
- <para>All logger allow the log event layout to be customised. Loggers understand <ulink
+ virtualhosts. These abilities can be usefully exploited together in managed service scenarios
+ to produce separate logs for separate user groups.</para>
+ <para>Loggers can be added or removed at runtime, which restarting the Broker. However changes
+ to a Logger's configuration such as filenames and rolling options don't take effect until the
+ next restart. Changes to a Logger's inclusion rules take effect immediately.</para>
+ <para>All loggers allow the log event layout to be customised. Loggers understand <ulink
url="http://logback.qos.ch/manual/layouts.html#ClassicPatternLayout"> Logback Classic
Pattern Layouts</ulink>. </para>
<para>The following sections describes each Logger implementation in detail.</para>
@@ -137,13 +136,15 @@
<para>The <emphasis>roll daily</emphasis> option, if enabled, will cause the log file will be
rolled at midnight local time. The rolled over file will have a suffix in the form
<literal>yyyy-mm-dd</literal>. In roll daily mode, <emphasis>maximum number of rolled
- files</emphasis> governs the number of days logs that will be retained.</para>
+ files</emphasis> controls the maximum number of <emphasis>days</emphasis> to be retained.
+ Older files will be deleted.</para>
<para>The <emphasis>maximum file size</emphasis> option limits the size of any one log file.
Once a log file reaches the given size, it will be rolled. The rolled over file will have
the numeric suffix, beginning at <literal>1</literal>. If the log file rolls again, first
the existing file with the suffix <literal>.1</literal> is renamed to <literal>.2</literal>
and so forth. If roll daily is not in use, <emphasis>maximum number of rolled
- files</emphasis> governs the number of rolled files that will be retained.</para>
+ files</emphasis> governs the <emphasis>number</emphasis> of rolled files that will be
+ retained.</para>
<para><emphasis>Roll on restart</emphasis> governs whether the log file is rolled when the
Broker is restarted. If not ticked, the Broker will append to the existing log file until it
needs to be rolled.</para>
@@ -159,7 +160,7 @@
<literal>USER</literal> facility. The hostname and port number of the syslog daemon can be
configured.</para>
<para>Log entries can be prefixed with a string. This string defaults to include the word
- <literal>Qpid</literal> and the name of the Broker or Virtualhost. This serves to
+ <literal>Qpid</literal> and the name of the Broker or virtualhost. This serves to
distinguish the logging generated by this Qpid instance, from other Qpid instances, or other
applications using the <literal>USER</literal>.</para>
</section>
@@ -168,7 +169,7 @@
<para><emphasis>MemoryLogger</emphasis> - writes a log file to a circular in-memory buffer. By
default the circular buffer holds the last 4096 log events. The contents of the buffer can
be viewed via Management. See <xref
- linkend="Java-Broker-Runtime-Logging-Management-MemoryLogger"/>></para>
+ linkend="Java-Broker-Runtime-Logging-Management-MemoryLogger"/></para>
</section>
</section>
<section id="Java-Broker-Runtime-Logging-InclusionRules">
@@ -181,42 +182,44 @@
<itemizedlist>
<listitem>
<para>The <emphasis>Name And Level</emphasis> inclusion rule accepts log events that match
- a given logger name and have a level that equals or exceeds the specified value.</para>
- <para>The logger name refers to the logger name declared in the Qpid source itself. Logger
- names permit a trailing wild card <literal>.*</literal>. For instance
- <literal>org.apache.qpid.*</literal> will match all Qpid loggers that begin
- <literal>org.apache.qpid.</literal>. </para>
+ a given <emphasis>log event source name</emphasis> and have a level that equals or
+ exceeds the specified value.</para>
+ <para>The log event source name refers to the logger name declared in the Qpid source code
+ itself. These names permit a trailing wild card <literal>.*</literal>. For instance a
+ source name of <literal>org.apache.qpid.*</literal> will match all events from classes
+ in the package <literal>org.apache.qpid</literal> and any sub packages beneath.</para>
<para>The <emphasis>Level</emphasis> governs the level of the events that will be included
- in the log. It may take a one of the following value: FATAL, ERROR, WARN, INFO, DEBUG,
- TRACE where FATAL is considered the highest and TRACE the lowest. When considering
- whether a logging event should be include in the log, the logging event must have a
- level that matches that of the inclusion rule or be higher, otherwise the log event will
- not appear in the log. </para>
+ in the log. It may take one of the following values: ERROR, WARN, INFO, DEBUG, TRACE
+ where ERROR is considered the highest and TRACE the lowest. In addition, there are two
+ special values: OFF and ALL, the former excludes all log events whereas the latter will
+ include everything. When considering whether a logging event should be included in the
+ log, the logging event must have a level that matches that of the inclusion rule or be
+ higher, otherwise the log event will not appear in the log.</para>
</listitem>
</itemizedlist>
</para>
</section>
<section id="Java-Broker-Runtime-Logging-Management">
<title>Logging Management</title>
- <para>The logging subsystem can be completely managed from the Web Management Console or the REST
- API. You can: <itemizedlist>
- <listitem><para>Add, remove or change the configuration of Loggers.</para></listitem>
- <listitem><para>Add, remove or change the Inclusion Rules.</para></listitem>
+ <para>The logging subsystem can be completely managed from the Web Management Console or the
+ REST API. You can: <itemizedlist>
+ <listitem><para>Add, remove, or change the configuration of Loggers.</para></listitem>
+ <listitem><para>Add, remove, or change the Inclusion Rules.</para></listitem>
<listitem><para>For FileLoggers, download the log file and rolled log files associated with
the Logger.</para></listitem>
<listitem><para>For MemoryLoggers, view the last <literal>n</literal> log
events</para></listitem>
</itemizedlist>
</para>
- <para> The figure that follows shows the a FileLogger. The attributes area shows the
- configuration of the Logger. The inclusion rule tables shows the rules that are associated
- with the Logger. The area towards the bottom of the tab allow the log files to be downloaded
- to the browser. <figure id="Java-Broker-Runtime-Logging-Management-FileLogger">
+ <para> The figure that follows shows a FileLogger. The attributes area shows the configuration
+ of the Logger. The inclusion rule table shows the rules that are associated with the Logger.
+ The area towards the bottom of the tab allow the log files to be downloaded to the browser.
+ <figure id="Java-Broker-Runtime-Logging-Management-FileLogger">
<title>Viewing a file logger</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/Management-Web-Logging-FileLogger.png" format="PNG"
- scalefit="1"/>
+ scalefit="1" width="900px"/>
</imageobject>
<textobject>
<phrase>Viewing a file logger</phrase>
@@ -230,7 +233,7 @@
<mediaobject>
<imageobject>
<imagedata fileref="images/Management-Web-Logging-InclusionRule.png" format="PNG"
- scalefit="1"/>
+ scalefit="1" width="900px"/>
</imageobject>
<textobject>
<phrase>Editing an inclusion rule</phrase>
@@ -245,7 +248,7 @@
<mediaobject>
<imageobject>
<imagedata fileref="images/Management-Web-Logging-MemoryLogger.png" format="PNG"
- scalefit="1"/>
+ scalefit="1" width="900px"/>
</imageobject>
<textobject>
<phrase>Viewing a memory logger</phrase>
Modified: qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml?rev=1709983&r1=1709982&r2=1709983&view=diff
==============================================================================
--- qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml (original)
+++ qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml Thu Oct 22 10:34:38 2015
@@ -21,9 +21,9 @@
-->
<section id="Java-Broker-Concepts-Overview">
<title>Overview</title>
- <para>The Broker comprises of a number of entities. This section summaries the purpose of
- each of the entities and describes the relationships between them. These details are developed
- further in the sub-sections that follow.</para>
+ <para>The Broker comprises of a number of entities. This section summaries the purpose of each of
+ the entities and describes the relationships between them. These details are developed further
+ in the sub-sections that follow.</para>
<para>The most important entity is the <emphasis>Virtualhost</emphasis>. A virtualhost is an
independent namespace in which messaging is performed. A <emphasis>virtualhost</emphasis> exists
in a container called a <emphasis>virtualhost node</emphasis>. A virtualhost node has exactly
@@ -48,11 +48,12 @@
<para><emphasis>Remote Replication Nodes</emphasis> are used when the high availability feature is
in use. It is the remote representation of other virtualhost nodes that form part of the same
group.</para>
- <para><emphasis>Loggers</emphasis> are responsible for the production of a log for either
- the Broker.</para>
+ <para><emphasis>Loggers</emphasis>, at this point in the hierarchy, are responsible for the
+ production of a log for the Broker.</para>
<para>These concepts will be developed over the forthcoming pages. The diagrams below also help
put these entities in context of one and other.</para>
- <para><figure>
+ <para>
+ <figure>
<title>Message Flow through Key Entities</title>
<mediaobject>
<imageobject>
@@ -62,8 +63,10 @@
<phrase>Message Flow through the Key Entities of the Broker</phrase>
</textobject>
</mediaobject>
- </figure></para>
- <para><figure>
+ </figure>
+ </para>
+ <para>
+ <figure>
<title>Broker Structure</title>
<mediaobject>
<imageobject>
Modified: qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml?rev=1709983&r1=1709982&r2=1709983&view=diff
==============================================================================
--- qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml (original)
+++ qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml Thu Oct 22 10:34:38 2015
@@ -23,8 +23,8 @@
<section id="Java-Broker-Concepts-Virtualhosts">
<title>Virtualhosts</title>
<para>A virtualhost is a namespace in which messaging is performed. Virtualhosts are independent;
- the messaging that goes on within one virtualhost is independent of any messaging that goes on in
- another virtualhost. For instance, a queue named <emphasis>foo</emphasis> defined in one
+ the messaging that goes on within one virtualhost is independent of any messaging that goes on
+ in another virtualhost. For instance, a queue named <emphasis>foo</emphasis> defined in one
virtualhost is completely independent of a queue named <emphasis>foo</emphasis> in another
virtualhost.</para>
<para>A virtualhost is identified by a name which must be unique broker-wide. Clients use the name
@@ -44,7 +44,7 @@
<para>A <emphasis>Session</emphasis> represents a context for the production or consumption of
messages. A Connection can have many Sessions.</para>
<para>A <emphasis>Consumer</emphasis> represents a live consumer that is attached to queue.</para>
- <para>A <emphasis>Logger</emphasis> is responsible for producing log for this virtualhost.</para>
+ <para><emphasis>Loggers</emphasis> are responsible for producing logs for this virtualhost.</para>
<para> The following diagram depicts the Virtualhost model: <figure>
<title>Virtualhost Model</title>
<mediaobject>
@@ -57,5 +57,6 @@
</mediaobject>
</figure>
</para>
- <para>A <emphasis>virtualhost</emphasis> is backed by storage which is used to store the messages.</para>
+ <para>A <emphasis>virtualhost</emphasis> is backed by storage which is used to store the
+ messages.</para>
</section>
Modified: qpid/java/trunk/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml?rev=1709983&r1=1709982&r2=1709983&view=diff
==============================================================================
--- qpid/java/trunk/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml (original)
+++ qpid/java/trunk/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml Thu Oct 22 10:34:38 2015
@@ -356,7 +356,7 @@
</itemizedlist>
</entry>
<entry>
- <para>Manages(creates/deletes/updates) Broker or Virtualhost Loggers(s) and provides the information about current values of the attributes. Some implementatiions have operations
+ <para>Manages(creates/deletes/updates) Broker or Virtualhost Loggers(s) and provides the information about current values of the attributes. Some implementations have operations
that allow the names of log files and log content to be retrieved.</para>
</entry>
</row>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org