<?xml version="1.0" encoding="UTF-8"?>
<!--
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  - JASMINe
  - Copyright (C) 2011-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.indicator_create" 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>Indicator definition</title>

  <sect2>
    <title>Create an indicator</title>

    <para>
      In order to define an indicator, users have to specify:
      <itemizedlist>
       <listitem>
         <para><emphasis role="bold">name</emphasis>: a user defined name that uniquely identifies the indicator.</para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">type</emphasis>: one of the available types depending on the current JASMINe Probe configuration.
         A management operation exists allowing to list the
         available types. The default configuration makes available all the indicator types described in the section below.</para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">scale</emphasis>: optional numeric value that defaults to 1; defines a scale for an indicator having a number as value.</para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">properties</emphasis>: depend on the type.</para>
       </listitem>
     </itemizedlist>
    </para>

    <xi:include href="indicator_types.xml" />

  </sect2>

  <sect2>
    <title>Define a jmx indicator</title>
    <para>
    <table>
      <title>Specific properties to define for a jmx indicator</title>
      <tgroup cols="2">
        <colspec colname="option" colwidth="2*" align="left" />
        <colspec colname="attributes" colwidth="5*" align="left" />
        <thead>
        <row>
          <entry spanname="span1" align="center" >Property name</entry>
          <entry align="center">Property value</entry>
        </row>
        </thead>
        <tbody>
          <row>
            <entry><emphasis role="bold">mbean</emphasis></entry>
            <entry>an OBJECT_NAME or an OBJECT_NAME pattern conform to the MBean ObjectName Syntax. Required. Allows to determine the MBean(s) to be polled</entry>
          </row>
          <row>
            <entry><emphasis role="bold">attr</emphasis></entry>
            <entry>list of <emphasis>attribute</emphasis>, or <emphasis>attribute fragment</emphasis> names</entry>
          </row>
          <row>
            <entry><emphasis role="bold">target</emphasis></entry>
            <entry>default target's name. Optional - if not specified, a target must be specified by a probe using this indicator</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    </para>

    <para>
       An attribute fragment is a part of an attribute's value, when the attribute has a complex type. See below for details.
     </para>
     <para>The <emphasis role="bold">attr</emphasis> property determines the attributes to be read from the MBeans. If not defined, all the attributed are read.</para>

     <para><emphasis role="bold">Examples:</emphasis></para>
     <screen>
  &lt;indicator name="procnb" type="jmx"&gt;
    &lt;property key="mbean" value="java.lang:type=OperatingSystem"/&gt;
    &lt;property key="attr" value="AvailableProcessors"/&gt;
  &lt;/indicator&gt;

  &lt;indicator name="gc_collection_count" type="jmx"&gt;
    &lt;property key="mbean" value="java.lang:type=GarbageCollector,*"/&gt;
    &lt;property key="attr" value="CollectionCount"/&gt;
  &lt;/indicator&gt;

  &lt;indicator name="threading" type="jmx"&gt;
    &lt;property key="mbean" value="java.lang:type=Threading"/&gt;
    &lt;property key="attr" value="TotalStartedThreadCount,ThreadCount,PeakThreadCount"/&gt;
  &lt;/indicator&gt;

  &lt;indicator name="memoryHeap" type="jmx"&gt;
    &lt;property key="mbean" value="java.lang:type=Memory"/&gt;
    &lt;property key="attr" value="HeapMemoryUsage"/&gt;
  &lt;/indicator&gt;
</screen>

    <sect3>
      <title>Attribute fragments</title>
      <para>
        In the case of an attribute having a complex value, the user may want to poll not the whole value, but only a part of it (a fragment), or several fragments.
      </para>
      <para>
        To specify an attribute fragment, the user must provide a <emphasis>fragment name</emphasis> based on the naming convention presented in <xref linkend="jasmineprobe.fragments"/>.
      </para>
      <para>
        The fragment name contains a &lt;base name&gt; given by the attribute name, and a sequence of &lt;fragment elements&gt; corresponding to the path from the base down to the part of attribute user wants to be polled.
      </para>
      <para>
        The <emphasis>fragment value</emphasis> is the part of the attribute's value corresponding to the path expressed by the fragment name.
      </para>
      <para>
        Let's consider for example the JVM MBean having OBJECT_NAME <emphasis>java.lang:type=Memory</emphasis>. The attribute named <emphasis>HeapMemoryUsage</emphasis> has a complex type (javax.management.openmbean.CompositeData).
        The posible key values are: <emphasis>commited</emphasis>, <emphasis>used</emphasis>, <emphasis>init</emphasis>, <emphasis>max</emphasis>.
        If the user wants to poll only the value corresponding to the <emphasis>use</emphasis> key, he specifies the fragment named <emphasis>HeapMemoryUsage.used</emphasis> as <emphasis role="bold">attr</emphasis> property value,
        instead of using the "<emphasis>HeapMemoryUsage</emphasis> attribute name.
        </para>
        <para>Here is the indicator definition, and some more attribute fragments examples:</para>
        <screen>
  &lt;indicator name="memoryHeapUsed" type="jmx"&gt;
    &lt;property key="mbean" value="java.lang:type=Memory"/&gt;
    &lt;property key="attr" value="HeapMemoryUsage.used"/&gt;
  &lt;/indicator&gt;

  &lt;indicator name="inputArg0" type="jmx"&gt;
    &lt;property key="mbean" value="java.lang:type=Runtime"/&gt;
    &lt;property key="attr" value="InputArguments[0]"/&gt;
  &lt;/indicator&gt;

  &lt;indicator name="propFileEncoding" type="jmx"&gt;
    &lt;property key="mbean" value="java.lang:type=Runtime"/&gt;
    &lt;property key="attr" value="SystemProperties[file.encoding]"/&gt;
  &lt;/indicator&gt;

        </screen>
    </sect3>

    <sect3>
      <title>Jmx indicator values</title>
      <para>
        Let's consider a probe that has in its definition the above <emphasis role="bold">jmx</emphasis> indicator named <emphasis>memoryHeapUsed</emphasis>.
        When running the probe, at each polling iteration, the indicator value is obtained by getting from the "HeapMemoryUsage" attribute's composite data, the value corresponding to the "used" key.
      </para>
      <para>
        What about the value obtained for another indicator, named <emphasis>memoryHeap</emphasis>, having the <emphasis role="bold">attr</emphasis> property set to "HeapMemoryUsage" ?
        In this case, the indicator value is composed of several values, one for each key. We call these values <emphasis role="bold">indicator results</emphasis>.
      </para>
      <para>
        A <emphasis role="bold">jmx</emphasis> indicator's value is composed of more then one indicator results in the following situations:
        <itemizedlist>
          <listitem>
            <para>several MBeans correspond to the <emphasis role="bold">mbean</emphasis> property (see indicator named <emphasis>gc_collection_count</emphasis> in the above examples)</para>
          </listitem>
          <listitem>
            <para>more than one elements are defined by the <emphasis role="bold">attr</emphasis> property (see indicator named <emphasis>threading</emphasis>)</para>
          </listitem>
          <listitem>
            <para>one of the attributes or fragments defined in the <emphasis role="bold">attr</emphasis> property has a complex value (see indicator named <emphasis>memoryHeap</emphasis>)</para>
          </listitem>
        </itemizedlist>
      </para>
      <para>
        Each result is identified by a name that is generated using the fragments naming convention presented in <xref linkend="jasmineprobe.fragments"/>.
        Each result's value has a simple type (a Number, String or Boolean).
      </para>
    </sect3>
  </sect2>

  <sect2>
    <title>Define a df indicator</title>
    <para>The following property may specify one or more device names to check: </para>
    <para>
      <itemizedlist>
       <listitem>
         <para><emphasis role="bold">disk</emphasis>: device path names relative to <emphasis>/dev</emphasis></para>
       </listitem>
      </itemizedlist>
    </para>
    <para>When the <emphasis role="bold">disk</emphasis> property is not defined, the available space, in percentage, for all the disks is to be obtained.</para>

    <para>
        A <emphasis role="bold">df</emphasis> indicator's value is composed of more then one indicator results if several devices are monitored.
    </para>
    <para>
        Each result is identified by a name that is equal to the device name.
        Each result's value is the used space on the device in percentage.
    </para>

     <para><emphasis role="bold">Examples:</emphasis></para>
     <screen>
  &lt;indicator name="df-sda1" type="df"&gt;
    &lt;property key="disk" value="sda1"/&gt;
  &lt;/indicator&gt;
</screen>

  </sect2>

  <sect2>
    <title>Define a lewys indicator</title>
    <para>Two properties must be defined for a lewys indicator:
      <itemizedlist>
       <listitem>
         <para><emphasis role="bold">cmd</emphasis>: a lewys command corresponding to the monitored resource type ; the possible values are <emphasis>disk</emphasis>, <emphasis>memory</emphasis>,
         <emphasis>network</emphasis>, <emphasis>cpu</emphasis> and <emphasis>kernel</emphasis> </para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">resources</emphasis>: a list of resource names (see the <emphasis>probe-config.xml</emphasis> configuration file for details)</para>
       </listitem>
      </itemizedlist>
    </para>

     <para><emphasis role="bold">Examples:</emphasis></para>
     <screen>
  &lt;indicator name="lewys-disk" type="lewys"&gt;
    &lt;property key="cmd" value="disk"/&gt;
    &lt;property key="resources" value="sda1 reads issued,sda1 reads merged,sda1 read sectors,sda1 read time in ms"/&gt;
  &lt;/indicator&gt;
</screen>

  </sect2>

  <sect2>
    <title>Define an aggregate (or merge) indicator</title>

    <para>
      The <emphasis role="bold">aggregate</emphasis> and <emphasis role="bold">merge</emphasis> indicators definition requires:
      <itemizedlist>
       <listitem>
         <para><emphasis role="bold">op</emphasis>: the aggregate operation ; the possible values are <emphasis>sum</emphasis>, <emphasis>average</emphasis>, <emphasis>max</emphasis> and <emphasis>min</emphasis></para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">source</emphasis>: source indicator name. The source indicator value must only have number results.</para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">merge</emphasis>: not implemented yet, its aim is to filter out some non relevant values from the aggregation.</para>
       </listitem>
      </itemizedlist>
    </para>

      <para>
        The value of an <emphasis role="bold">aggregate</emphasis> or <emphasis role="bold">merge</emphasis> indicator contains one result.
        Its value is obtained by aggregation of the source indicator's results.
      </para>


     <para><emphasis role="bold">Examples:</emphasis></para>
     <screen>
  &lt;indicator name="gc_collection_count" type="jmx"&gt;
    &lt;property key="mbean" value="java.lang:type=GarbageCollector,*"/&gt;
    &lt;property key="attr" value="CollectionCount"/&gt;
  &lt;/indicator&gt;

  &lt;indicator name="total_gc_collection_count" type="aggregate"&gt;
    &lt;property key="op" value="sum"/&gt;
    &lt;source&gt;gc_collection_count&lt;/source&gt;
  &lt;/indicator&gt;
</screen>
  </sect2>

  <sect2>
    <title>Define a correlate indicator</title>

    <para>
      The <emphasis role="bold">correlate</emphasis> indicator definition requires:
      <itemizedlist>
       <listitem>
         <para><emphasis role="bold">op</emphasis>: the correlate operation ; the possible values are <emphasis>add</emphasis>, <emphasis>sub</emphasis>, <emphasis>mul</emphasis>, <emphasis>div</emphasis>, <emphasis>percent</emphasis></para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">sources</emphasis>: source indicator names. Source indicator values must be numbers.</para>
       </listitem>
      </itemizedlist>
    </para>

    <para>
      Current limitation: all the source indicators values must contain only one result.
    </para>

        <para><emphasis role="bold">Examples:</emphasis></para>
      <itemizedlist>
       <listitem>
         <para><emphasis role="bold">type</emphasis>: one of the followings are accepted <emphasis>long</emphasis>, <emphasis>int</emphasis>,
         <emphasis>float</emphasis>, <emphasis>double</emphasis></para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">value</emphasis>: the constant value</para>
       </listitem>
      </itemizedlist>
        <screen>
  &lt;indicator name="memoryHeapUsed" type="jmx"&gt;
    &lt;property key="mbean" value="java.lang:type=Memory"/&gt;
    &lt;property key="attr" value="HeapMemoryUsage.used"/&gt;
  &lt;/indicator&gt;

  &lt;indicator name="memoryHeapCommitted" type="jmx"&gt;
    &lt;property key="mbean" value="java.lang:type=Memory"/&gt;
    &lt;property key="attr" value="HeapMemoryUsage.committed"/&gt;
  &lt;/indicator&gt;

  &lt;indicator name="memoryHeapUsedPercent" type="correlate"&gt;
    &lt;property key="op" value="percent"/&gt;
    &lt;source&gt;memoryHeapUsed&lt;/source&gt;
    &lt;source&gt;memoryHeapCommitted&lt;/source&gt;
  &lt;/indicator&gt;

        </screen>

  </sect2>

  <sect2>
    <title>Define a derived indicator</title>

    <para>
      The <emphasis role="bold">derived</emphasis> indicator definition requires:
      <itemizedlist>
       <listitem>
         <para><emphasis role="bold">op</emphasis>: the derived operation ; the possible values are <emphasis>prev</emphasis>, <emphasis>delta</emphasis>, <emphasis>rate</emphasis>,
         having the following meanings:
         </para>
         <para>
           <itemizedlist>
             <listitem>
               <para><emphasis role="bold">prev</emphasis>: at each iteration, return the results corresponding to the previous iteration,</para>
             </listitem>
             <listitem>
               <para><emphasis role="bold">delta</emphasis>: at each iteration and each result, return the value corresponding to the current iteration, minus the value corresponding to the previous iteration,</para>
             </listitem>
             <listitem>
               <para><emphasis role="bold">rate</emphasis>: at each iteration and for each result, return the delta(v)/delta(t),</para>
             </listitem>
           </itemizedlist>
         </para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">sources</emphasis>: source indicator name. The source indicator value may be composed of several results, but the result values must only be numbers.</para>
       </listitem>
      </itemizedlist>
    </para>

    <para>
        The value of an <emphasis role="bold">derived</emphasis> indicator is composed of as many results as the source indicator's value.
        Each result in the derived indicator value is obtained by applying the derived operation on one result in the source indicator value.
    </para>


     <para><emphasis role="bold">Examples:</emphasis></para>
     <screen>
  &lt;indicator name="totalStartedThreadCount" type="jmx"&gt;
    &lt;property key="mbean" value="java.lang:type=Threading"/&gt;
    &lt;property key="attr" value="TotalStartedThreadCount"/&gt;
  &lt;/indicator&gt;

  &lt;indicator name="deltaStartedThreadCount" type="derived"&gt;
    &lt;property key="op" value="delta"/&gt;
    &lt;source&gt;totalStartedThreadCount&lt;/source&gt;
  &lt;/indicator&gt;
</screen>
  </sect2>

  <sect2>
    <title>Define a slope indicator</title>

    <para>Two sources must be defined for a slope indicator, both corresponding to a source indicator.
    The first one for the <emphasis>numerator</emphasis>, and the second one for the <emphasis>denominator</emphasis>.</para>
    The slope value corresponds to <emphasis>(delta(s1) / delta(s2))</emphasis>.
    <para>
      Current limitation: both source indicators must have values composed of only one result.
    </para>

  </sect2>

  <sect2>
    <title>Define a constant indicator</title>
    <para>The following properties must be specified: </para>
    <para>
      <itemizedlist>
       <listitem>
         <para><emphasis role="bold">type</emphasis>: one of the followings are accepted <emphasis>long</emphasis>, <emphasis>int</emphasis>,
         <emphasis>float</emphasis>, <emphasis>double</emphasis></para>
       </listitem>
       <listitem>
         <para><emphasis role="bold">value</emphasis>: the constant value</para>
       </listitem>
      </itemizedlist>
    </para>

     <para><emphasis role="bold">Example:</emphasis></para>
     <screen>
  &lt;indicator name="1K" type="constant"&gt;
    &lt;property key="type" value="int"/&gt;
    &lt;property key="value" value="1000000"/&gt;
  &lt;/indicator&gt;
     </screen>
  </sect2>

</sect1>
