Adding OpenFlow Plugin message spy docs

Change-Id: I2d14600cb523a4b77d3e09a90061e7ef780170a4
Signed-off-by: Colin Dixon <colin@colindixon.com>
(cherry picked from commit d3d47bdac21a70b6963575a17c87fc5c01f799aa)

diff --git a/manuals/developer-guide/src/main/asciidoc/openflowplugin/odl-ofp-developer-guide.adoc b/manuals/developer-guide/src/main/asciidoc/openflowplugin/odl-ofp-developer-guide.adoc
index b889957095bd141d1bd94dde75d355a9f9445c77..8b5b4f9e70074773e9c3fd026359517021dc9912 100644 (file)
--- a/manuals/developer-guide/src/main/asciidoc/openflowplugin/odl-ofp-developer-guide.adoc
+++ b/manuals/developer-guide/src/main/asciidoc/openflowplugin/odl-ofp-developer-guide.adoc
@@ -11,7 +11,7 @@ include::odl-ofp-sequence-diagram.adoc[]
 
 // include::odl-ofp-config-subsystem.adoc[]
 
-// include::odl-ofp-message-spy.adoc[]
+include::odl-ofp-message-spy.adoc[]
 
 // * OpenDaylight_OpenFlow_Plugin:Backlog:Extensibility[Extensibility Framework]
 

diff --git a/manuals/developer-guide/src/main/asciidoc/openflowplugin/odl-ofp-message-spy.adoc b/manuals/developer-guide/src/main/asciidoc/openflowplugin/odl-ofp-message-spy.adoc
new file mode 100644 (file)
index 0000000..683daec
--- /dev/null
+++ b/manuals/developer-guide/src/main/asciidoc/openflowplugin/odl-ofp-message-spy.adoc
@@ -0,0 +1,117 @@
+=== Internal message statistics API
+
+To aid in testing and diagnosis, the OpenFlow plugin provides information about the number and rate of different internal events.
+
+=== Implemented strategy
+
+The implementation does two things: collects event counts and exposes counts. Event counts are grouped by message type, e.g., *PacketInMessage*, and checkpoint, e.g., _TO_SWITCH_ENQUEUED_SUCCESS_. Once gathered, the results are logged as well as being exposed using OSGi command line (deprecated) and JMX.
+
+[[collect]]
+==== Collect
+
+Each message is counted as it passes through various processing checkpoints. The following checkpoints are defined as a Java enum and tracked:
+
+[source, java]
+----
+  /**
+    * statistic groups overall in OFPlugin
+    */
+  enum STATISTIC_GROUP {
+       /** message from switch, enqueued for processing */
+       FROM_SWITCH_ENQUEUED,
+       /** message from switch translated successfully - source */
+       FROM_SWITCH_TRANSLATE_IN_SUCCESS,
+       /** message from switch translated successfully - target */
+       FROM_SWITCH_TRANSLATE_OUT_SUCCESS,
+       /** message from switch where translation failed - source */
+       FROM_SWITCH_TRANSLATE_SRC_FAILURE,
+       /** message from switch finally published into MD-SAL */
+       FROM_SWITCH_PUBLISHED_SUCCESS,
+       /** message from switch - publishing into MD-SAL failed */
+       FROM_SWITCH_PUBLISHED_FAILURE,
+       
+       /** message from MD-SAL to switch via RPC enqueued */
+       TO_SWITCH_ENQUEUED_SUCCESS,
+       /** message from MD-SAL to switch via RPC NOT enqueued */
+       TO_SWITCH_ENQUEUED_FAILED,
+       /** message from MD-SAL to switch - sent to OFJava successfully */
+       TO_SWITCH_SUBMITTED_SUCCESS,
+       /** message from MD-SAL to switch - sent to OFJava but failed*/
+       TO_SWITCH_SUBMITTED_FAILURE
+  }
+----
+
+When a message passes through any of those checkpoints then counter assigned to
+corresponding checkpoint and message is incremented by 1.
+
+[[expose-results]]
+==== Expose statistics
+
+As described above, there are three ways to access the statistics:
+
+* OSGi command line (this is considered deprecated)
++
+::
+  `osgi> dumpMsgCount`
+* OpenDaylight logging console (statistics are logged here every 10 seconds)
++
+::
+  required logback settings :
+  `<logger name="org.opendaylight.openflowplugin.openflow.md.queue.MessageSpyCounterImpl" level="DEBUG"\/>`
+* JMX (via JConsole)
+::
+  start OpenFlow plugin with the +-jmx+ parameter
+::
+  start JConsole by running `jconsole`
+::
+  the JConsole MBeans tab should contain org.opendaylight.controller
+::
+  RuntimeBean has a msg-spy-service-impl
+::
+  Operations provides makeMsgStatistics report functionality
+
+[[example-result]]
+===== Example results
+
+image::openflowplugin/odl-ofp-ofplugin-debug-stats.png[OFplugin Debug stats.png,title="OFplugin Debug stats.png" width="500"]
+
+----
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_ENQUEUED: MSG[PortStatusMessage] -> +0 | 1
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_ENQUEUED: MSG[MultipartReplyMessage] -> +24 | 81
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_ENQUEUED: MSG[PacketInMessage] -> +8 | 111
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_IN_SUCCESS: MSG[PortStatusMessage] -> +0 | 1
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_IN_SUCCESS: MSG[MultipartReplyMessage] -> +24 | 81
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_IN_SUCCESS: MSG[PacketInMessage] -> +8 | 111
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[QueueStatisticsUpdate] -> +3 | 7
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[NodeUpdated] -> +0 | 3
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[NodeConnectorStatisticsUpdate] -> +3 | 7
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[GroupDescStatsUpdated] -> +3 | 7
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[FlowsStatisticsUpdate] -> +3 | 19
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[PacketReceived] -> +8 | 111
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[MeterFeaturesUpdated] -> +0 | 3
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[GroupStatisticsUpdated] -> +3 | 7
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[GroupFeaturesUpdated] -> +0 | 3
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[MeterConfigStatsUpdated] -> +3 | 7
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[MeterStatisticsUpdated] -> +3 | 7
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[NodeConnectorUpdated] -> +0 | 12
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[FlowTableStatisticsUpdate] -> +3 | 8
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_SRC_FAILURE: no activity detected
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[QueueStatisticsUpdate] -> +3 | 7
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[NodeUpdated] -> +0 | 3
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[NodeConnectorStatisticsUpdate] -> +3 | 7
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[GroupDescStatsUpdated] -> +3 | 7
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[FlowsStatisticsUpdate] -> +3 | 19
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[PacketReceived] -> +8 | 111
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[MeterFeaturesUpdated] -> +0 | 3
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[GroupStatisticsUpdated] -> +3 | 7
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[GroupFeaturesUpdated] -> +0 | 3
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[MeterConfigStatsUpdated] -> +3 | 7
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[MeterStatisticsUpdated] -> +3 | 7
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[NodeConnectorUpdated] -> +0 | 12
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[FlowTableStatisticsUpdate] -> +3 | 8
+DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_FAILURE: no activity detected
+DEBUG o.o.o.s.MessageSpyCounterImpl - TO_SWITCH_ENQUEUED_SUCCESS: MSG[AddFlowInput] -> +0 | 12
+DEBUG o.o.o.s.MessageSpyCounterImpl - TO_SWITCH_ENQUEUED_FAILED: no activity detected
+DEBUG o.o.o.s.MessageSpyCounterImpl - TO_SWITCH_SUBMITTED_SUCCESS: MSG[AddFlowInput] -> +0 | 12
+DEBUG o.o.o.s.MessageSpyCounterImpl - TO_SWITCH_SUBMITTED_FAILURE: no activity detected
+----

diff --git a/manuals/developer-guide/src/main/resources/images/openflowplugin/odl-ofp-ofplugin-debug-stats.png b/manuals/developer-guide/src/main/resources/images/openflowplugin/odl-ofp-ofplugin-debug-stats.png
new file mode 100644 (file)
index 0000000..ec2ecd7
Binary files /dev/null and b/manuals/developer-guide/src/main/resources/images/openflowplugin/odl-ofp-ofplugin-debug-stats.png differ