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 2017/10/15 12:39:03 UTC
qpid-broker-j git commit: QPID-7799: [Statistics Reporting]
[Documentation] Add statistics reporting documentation
Repository: qpid-broker-j
Updated Branches:
refs/heads/master a0eccb5cf -> 51764e734
QPID-7799: [Statistics Reporting] [Documentation] Add statistics reporting documentation
Project: http://git-wip-us.apache.org/repos/asf/qpid-broker-j/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-broker-j/commit/51764e73
Tree: http://git-wip-us.apache.org/repos/asf/qpid-broker-j/tree/51764e73
Diff: http://git-wip-us.apache.org/repos/asf/qpid-broker-j/diff/51764e73
Branch: refs/heads/master
Commit: 51764e7349a01dbbaf7f1af610d8db660d75e2cf
Parents: a0eccb5
Author: Keith Wall <ke...@gmail.com>
Authored: Sun Oct 15 13:38:13 2017 +0100
Committer: Keith Wall <ke...@gmail.com>
Committed: Sun Oct 15 13:38:13 2017 +0100
----------------------------------------------------------------------
.../docbkx/AMQP-Messaging-Broker-Java-Book.xml | 1 +
...ava-Broker-Appendix-Statistics-Reporting.xml | 105 +++++++++++++++++++
...va-Broker-Management-Channel-Web-Console.xml | 2 +-
3 files changed, 107 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/51764e73/doc/java-broker/src/docbkx/AMQP-Messaging-Broker-Java-Book.xml
----------------------------------------------------------------------
diff --git a/doc/java-broker/src/docbkx/AMQP-Messaging-Broker-Java-Book.xml b/doc/java-broker/src/docbkx/AMQP-Messaging-Broker-Java-Book.xml
index 888d891..2b4b9af 100644
--- a/doc/java-broker/src/docbkx/AMQP-Messaging-Broker-Java-Book.xml
+++ b/doc/java-broker/src/docbkx/AMQP-Messaging-Broker-Java-Book.xml
@@ -37,6 +37,7 @@
<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-Statistics-Reporting.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-Queue-Alerts.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-Miscellaneous.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-Queue-Declaration-Arguments.xml"/>
http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/51764e73/doc/java-broker/src/docbkx/Java-Broker-Appendix-Statistics-Reporting.xml
----------------------------------------------------------------------
diff --git a/doc/java-broker/src/docbkx/Java-Broker-Appendix-Statistics-Reporting.xml b/doc/java-broker/src/docbkx/Java-Broker-Appendix-Statistics-Reporting.xml
new file mode 100644
index 0000000..8970cbc
--- /dev/null
+++ b/doc/java-broker/src/docbkx/Java-Broker-Appendix-Statistics-Reporting.xml
@@ -0,0 +1,105 @@
+<?xml version="1.0"?>
+<!--
+ ~
+ ~ 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 xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Java-Broker-Appendix-Statistics-Reporting">
+ <title>Statistics Reporting</title>
+ <para>The Broker has the ability to periodically write statistics of any entity within the system to
+ the log. Statistics can be enabled for a single entity (e.g. a queue) or for all entities of a particular
+ class (e.g. for all queues). The system can be configured dynamically at runtime without the need for the
+ system to be restarted.</para>
+ <para>This feature helps allow the behaviour of the overall system to be understood and can aid real-time problem
+ diagnosis.</para>
+ <para>It can be configured Broker-wide or separately for each virtual host.</para>
+ <para>The format of the statistics report is configurable.</para>
+ <section>
+ <title>Statistics Report Period</title>
+ <para>This governs the period with which statistics reports will be written to the log. The period is defined
+ in seconds. By default the statistics report period is zero, meaning the system is disabled. To enable the
+ statistics report set the <emphasis>statistics reporting period</emphasis> on either the Broker or virtualhost to
+ a non-zero value.</para>
+ <para>Once the period is defined, the system will respond to the statistic report patterns defined described next.</para>
+ </section>
+ <section>
+ <title>Statistic Report Patterns</title>
+ <para>The statistic report pattern defines the format of a statistic report written to the log.</para>
+ <para>Statistic report patterns are defined by <link linkend="Java-Broker-Management-Managing-Entities-General">
+ content variables</link>. The place where the context variable is definedgoverns the scope i.e. the entities to
+ which the pattern will be applied.</para>
+ <para>For instance, to define a statistics reporting pattern for a single queue,
+ <link linkend="Java-Broker-Management-Channel-Web-Console-Managing-Context-Variables">set the contextvariable
+ </link> on the queue itself. If you want the same statistics report pattern for apply to all queues, set the pattern on a
+ suitable ancestor of the queue. For instance, if set on virtualhost, the pattern will applied to all queues defined
+ on that virtualhost. If set on Broker, the pattern will be applied to all queues on the Broker.</para>
+ <para>The context variable name is formed as follows:
+ <literal>qpid.<category-name>.statisticsReportPattern</literal>.</para>
+ <para>For instance, for queue: <literal>qpid.queue.statisticsReportPattern</literal> and virtualhost:
+ <literal>qpid.virtualhost.statisticsReportPattern</literal></para>
+ <para>The value of the context variable is a free text string containing reference(s) to the statistic names that
+ are to appear in the report. References are made by surrounding the name of the statistic thus
+ <literal>${<statistic-name></literal>.</para>
+ <para>Statistics references allow an optional formatters. The supported formatters are: <literal>:byteunit</literal>
+ (produces a human readable byte value e.g. 3 MiB), <literal>:duration</literal> (produces a ISO-8601 duration)and
+ <literal>:datetime</literal> (produces a ISO-8601 date/time).</para>
+ <para>For example, a statistic report pattern for the <literal>queue</literal> category specifying two queue
+ statistic values: <literal>queueDepthMessages=${queueDepthMessages},queueDepthBytes=${queueDepthBytes:byteunit}</literal></para>
+ <para>Like all context variables, the statistic report pattern can also reference the attributes of the entity
+ or even its ancestors. This feature can be exploited to include things like the name of the entity within the
+ report.</para>
+ <para>These points are illustrated in the examples in the next section.</para>
+ <para>A catalogue of statistics names and descriptions is available from the REST API documentation available
+ through the <link linkend="Java-Broker-Management-Channel-Web-Console">Web Management Console</link>.</para>
+ </section>
+ <section>
+ <title>Examples</title>
+ <para>Adding a statistic reporting pattern to a single queue, called <literal>myqueue</literal> using the REST API and
+ cURL. This example uses <literal>ancestor</literal> references to include entity names:</para>
+ <example>
+ <title>Enabling statistics for a single queue using the REST API and cURL</title>
+ <screen><![CDATA[curl --user admin --data '{"name" : "qpid.queue.statisticsReportPattern", "value" : "${ancestor:virtualhost:name}/${ancestor:queue:name}: queueDepthMessages=${queueDepthMessages}, queueDepthBytes=${queueDepthBytes:byteunit}"}' https://localhost:8080/api/latest/queue/default/default/myqueue/setContextVariable]]></screen>
+ </example>
+ <para>
+ Once enabled, an example statistic report output written to the log might look like this:
+ <example>
+ <screen><![CDATA[2017-10-15 13:03:12,993 INFO [virtualhost-default-pool-0] (q.s.Queue) - Statistics: default/myqueue: queueDepthMessages=0, queueDepthBytes=0 B
+2017-10-15 13:03:22,979 INFO [virtualhost-default-pool-2] (q.s.Queue) - Statistics: default/myqueue: queueDepthMessages=3, queueDepthBytes=345 B
+2017-10-15 13:03:32,981 INFO [virtualhost-default-pool-2] (q.s.Queue) - Statistics: default/myqueue: queueDepthMessages=3, queueDepthBytes=345 B]]></screen>
+ </example>
+ </para>
+ <para>Removing a statistic report pattern from the same queue:</para>
+ <example>
+ <title>Diabling statistics for a single queue using the REST API and cURL</title>
+ <screen><![CDATA[curl --user admin --data '{"name" : "qpid.queue.statisticsReportPattern"}' https://localhost:8080/api/latest/queue/default/default/myqueue/setContextVariable]]></screen>
+ </example>
+ <para>Adding a statistic reporting pattern to all queues:</para>
+ <example>
+ <title>Enabling statistics for all queues using the REST API and cURL</title>
+ <screen><![CDATA[curl --user admin --data '{"name" : "qpid.queue.statisticsReportPattern", "value" : "${ancestor:virtualhost:name}/${ancestor:queue:name}: oldestMessageAge=${oldestMessageAge:duration}"}' https://localhost:8080/api/latest/virtualhost/default/default/setContextVariable]]></screen>
+ </example>
+ <para>
+ Once enabled, an example statistic report for a virtualhost with two queues might look like this:
+ <example>
+ <screen><![CDATA[2017-10-15 13:17:42,918 INFO [virtualhost-default-pool-1] (q.s.Queue) - Statistics: default/myqueue1: oldestMessageAge=PT1M24S
+2017-10-15 13:17:42,918 INFO [virtualhost-default-pool-1] (q.s.Queue) - Statistics: default/myqueue2: oldestMessageAge=PT0S]]></screen>
+ </example>
+ </para>
+ </section>
+</appendix>
http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/51764e73/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-Web-Console.xml
----------------------------------------------------------------------
diff --git a/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-Web-Console.xml b/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-Web-Console.xml
index 47b2c2c..6091d51 100644
--- a/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-Web-Console.xml
+++ b/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-Web-Console.xml
@@ -203,7 +203,7 @@
<imagedata fileref="images/Management-Web-ContextVar.png" format="PNG" scalefit="1"/>
</imageobject>
<textobject>
- <phrase>Editting Context Variables</phrase>
+ <phrase>Editing Context Variables</phrase>
</textobject>
</mediaobject>
</figure>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org