<?xml version="1.0" encoding="UTF-8"?>
<!--
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  - JASMINe
  - Copyright (C) 2012 Bull S.A.S.
  - Contact: jasmine@ow2.org
  -
  - This library is free software; you can redistribute it and/or
  - modify it under the terms of the GNU Lesser General Public
  - License as published by the Free Software Foundation; either
  - version 2.1 of the License, or any later version.
  -
  - This library is distributed in the hope that it will be useful,
  - but WITHOUT ANY WARRANTY; without even the implied warranty of
  - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  - Lesser General Public License for more details.
  -
  - You should have received a copy of the GNU Lesser General Public
  - License along with this library; if not, write to the Free Software
  - Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
  - USA
  -
  -
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  - $Id$
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
<sect1 version="5.0" xml:lang="en" xml:id="jasmineprobe.outforms" xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:svg="http://www.w3.org/2000/svg"
  xmlns:mml="http://www.w3.org/1998/Math/MathML"
  xmlns:html="http://www.w3.org/1999/xhtml"
  xmlns:db="http://docbook.org/ns/docbook">

  <title>Output formats for indicator values</title>
  <para>
    At each iteration, the probe collects the values corresponding to each indicator specified in its definition.
  </para>
  <para>
    For each indicator, one or more results are published by the outputs. They correspond to <emphasis>JasmineSingleResult</emphasis> instances referenced
    by the <emphasis>JasmineIndicatorValue</emphasis> instance (by its <emphasis>values</emphasis> attribute).
  </para>
  <para>
    Each result is published in a format that depends on the output type.
  </para>
  <para>
    The examples below presents the indicator values for a running a probe <emphasis>p2indic</emphasis> having two indicators,
    <emphasis>used-memory</emphasis> which is a <emphasis>jmx</emphasis> indicator, and a <emphasis>df</emphasis> indicator named <emphasis>dfi</emphasis>.
  </para>
    <screen>
    &lt;probe id="p2indic" period="20"&gt;
      &lt;indicator&gt;used-memory&lt;/indicator&gt;
      &lt;indicator&gt;dfi&lt;/indicator&gt;
      &lt;output&gt;stdio&lt;/output&gt;
      &lt;output&gt;log&lt;/output&gt;
      &lt;output&gt;jm&lt;/output&gt;
    &lt;/probe&gt;
    &lt;indicator name="used-memory" type="jmx"/&gt;
      &lt;property key="mbean" value="java.lang:type=Memory"/&gt;
      &lt;property key="attr" value="HeapMemoryUsage.used"/&gt;
      &lt;property key="target" value="agent0"/&gt;
    &lt;/indicator&gt;
    &lt;indicator name="dfi" type="df"/&gt;
    &lt;output name="stdio" type="console"/&gt;
    &lt;output name="log" type="file"/&gt;
      &lt;property key="path" value="/tmp/f1"/&gt;
    &lt;/output&gt;
    &lt;output name="jm" type="mule"&gt;
      &lt;property key="url" value="tcp://localhost:18564/JProbe"/&gt;
    &lt;/output&gt;
    &lt;target name="agent0" type="jmx"/&gt;
      &lt;property key="url" value="service:jmx:rmi:///jndi/rmi://localhost:4099/jrmpconnector_jasmine-probe"/&gt;
    &lt;/target&gt;
    </screen>
  <sect2>
    <title>Console output format</title>
    <para>For each result a line is printed to the console terminal. It contains elements separated by the ";" character.</para>
    <para>
    <screen>
      probeName;time;date;targetName;name;resultValue;props
    </screen>
    </para>
    <para>
      <itemizedlist>
       <listitem>
         <para><emphasis role="bold">probeName</emphasis>: the name provided by the probe definition, or generated by JASMINe Probe if no name provided</para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">time</emphasis>: <emphasis role="bold">timestamp</emphasis> in <emphasis>JasmineSingleResult</emphasis> </para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">date</emphasis>: <emphasis role="bold">time</emphasis> having "yyyy/MM/dd HH:mm:ss" format </para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">targetName</emphasis>: <emphasis role="bold">target</emphasis> in <emphasis>JasmineIndicatorValue</emphasis>. Note that when no explicit target artifact is required, the targetName is replaced by the host name.</para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">name</emphasis>:
         <itemizedlist>
           <listitem>
             <para><emphasis role="bold">indicatorName</emphasis> in the following cases: </para>
             <para><emphasis>Raw indicators:</emphasis></para>
             <para>the indicator defines one value to poll and the value has a simple type</para>
             <para></para>
             <para><emphasis>Processing indicators:</emphasis></para>
             <para>the indicator produces one simple type value</para>
           </listitem>
           <listitem>
             <para><emphasis role="bold">indicatorName.resultName</emphasis> when several simple values are obtained for the indicator</para>
           </listitem>
         </itemizedlist>
         <para>Where <emphasis role="bold">indicatorName</emphasis> is provided by <emphasis role="bold">name</emphasis> in <emphasis>JasmineIndicatorValue</emphasis>,
         and <emphasis role="bold">resultName</emphasis> is provided by <emphasis role="bold">name</emphasis> in <emphasis>JasmineSingleResult</emphasis></para>
         </para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">resultValue</emphasis>: <emphasis role="bold">value</emphasis> in <emphasis>JasmineSingleResult</emphasis> </para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">props</emphasis>: a sequence of <emphasis>propName=propValue</emphasis> elements corresponding to <emphasis role="bold">metadata</emphasis> in <emphasis>JasmineIndicatorValue</emphasis>
         and <emphasis>properties</emphasis> in<emphasis>JasmineSingleResult</emphasis>.</para>
       </listitem>
     </itemizedlist>
    </para>
    <para>Example below presents values published for <emphasis>p2indic</emphasis> probe. This probe has two indicators, a jmx indicator named <emphasis>used-memory</emphasis>,
          and a df indicator named <emphasis>dfi</emphasis>.
    <screen>
      p2indic;1327676884394;2012/01/27 16:08:04;agent0;used-memory;79207464;domain=jonas;server=jasmine-probe;url=service:jmx:rmi:///jndi/rmi://localhost:4099/jrmpconnector_jasmine-probe;mbean=java.lang:type=Memory
      \_____/ \___________/ \_________________/ \____/ \_________/ \______/ \________________________________________________________________________________________________________________________________________/
        |          |                 |            |         |         |                                                                |
     probeName    time              date      targetName  name    resultValue                        props composed by domain and server JIV properties values and mbean JSR property value
                                                            |
                                                      indicatorName

      p2indic;1327678833790;2012/01/27 16:40:33;bikini.frec.bull.fr;dfi.sda1;60;domain=jonas;server=jasmine-probe
      p2indic;1327678833790;2012/01/27 16:40:33;bikini.frec.bull.fr;dfi.sda4;59;domain=jonas;server=jasmine-probe
      \_____/ \___________/ \_________________/ \_________________/ \______/ \_/ \_______________________________/
        |          |                 |                   |              |     |                     |
     probeName    time              date             targetName       name resultValue  props composed by domain and server JIV properties
                                                                        |
                                                             indicatorName.resultName
    </screen>
    </para>
    <para>
      The elements composing the <emphasis>props</emphasis> can be used to get information about the target and the resource being monitored. Moreover, in some situation it allows to distinguish between
      different values having the same name. For example, suppose that the <emphasis>p2indic</emphasis> probe contains only one jmx indicator named <emphasis>used-memory</emphasis>. Suppose that
      the probe specifies two targets named <emphasis>t1</emphasis> and <emphasis>t2</emphasis>. The two values are published having the same <emphasis>name</emphasis> but different <emphasis>targetNames</emphasis>,
      and possible different <emphasis>server</emphasis> properties.
    </para>
    <para>
      Another typical jmx indicator example is an indicator defining a <emphasis>mbean</emphasis> property having as value a pattern that corresponds to several MBeans in the target server. In this case,
      several values are published having the same <emphasis>name</emphasis> but different <emphasis>mbean</emphasis> property.
    </para>
  </sect2>

  <sect2>
    <title>File output format</title>
    <para>For each result a line is printed to the file. It contains elements separated by the ";" character.</para>
    <para>
    <screen>
      time;date;targetName;props;resultValue
    </screen>
    </para>
    <para>
      <itemizedlist>
       <listitem>
         <para><emphasis role="bold">time</emphasis>: <emphasis role="bold">timestamp</emphasis> in <emphasis>JasmineSingleResult</emphasis> </para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">date</emphasis>: <emphasis role="bold">time</emphasis> having "yyyy/MM/dd HH:mm:ss" format </para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">targetName</emphasis>: <emphasis role="bold">target</emphasis> in <emphasis>JasmineIndicatorValue</emphasis>.
         Note that when no explicit target artifact is required, the targetName is replaced by the host name.</para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">props</emphasis>: a sequence of property values from <emphasis role="bold">metadata</emphasis> in <emphasis>JasmineIndicatorValue</emphasis>
         (the ones corresponding to <emphasis role="bold">domain</emphasis> and <emphasis role="bold">server</emphasis>) and
         the <emphasis role="bold">mbean</emphasis> property value in<emphasis>JasmineSingleResult</emphasis>'s <emphasis role="bold">properties</emphasis>,
         combined with the indicator name and result name (<emphasis role="bold">mbean:indicatorName</emphasis> or <emphasis role="bold">mbean:indicatorName.resultName</emphasis>).</para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">resultValue</emphasis>: <emphasis role="bold">value</emphasis> in <emphasis>JasmineSingleResult</emphasis> </para>
       </listitem>
     </itemizedlist>
    </para>
    <para>Example
    <screen>
      1327676884394;2012/01/27 16:08:04;agent0;jonas;jasmine-probe;java.lang:type=Memory:used-memory;79207464
      \___________/ \_________________/ \____/ \___________________________________________________/ \______/
           |                 |             |                            |                               |
          time              date         targetName                    props                        resultValue
                                                                        |
                                                ___________________________________________________
                                               /                                                   \
                                                      domain;server;mbean:indicatorName
    </screen>
    </para>
  </sect2>

  <sect2>
    <title>Mule output format</title>
    <para>
    <para>For each result 3 lines are published to the JASMINe Monitoring event bus. The first line only contains a format version number. The second contains a header that describes the elements of the third line.
    The header elements and the data elements from the third line are separated by the ";" character. Here are the header and data lines format:</para>
    <screen>
      <emphasis role="bold">cmdid</emphasis>;<emphasis role="bold">time</emphasis>;<emphasis role="bold">domain</emphasis>;<emphasis role="bold">server</emphasis>;<emphasis role="bold">sname</emphasis>;<emphasis role="bold">mbean</emphasis>;<emphasis>name</emphasis>
      <emphasis>probeName</emphasis>;<emphasis>date</emphasis>;<emphasis>domainName</emphasis>;<emphasis>serverName</emphasis>;<emphasis>targetName</emphasis>;<emphasis>mbeanName</emphasis>;<emphasis>value</emphasis>
    </screen>
    </para>
  </sect2>
</sect1>
