path: root/qpid/doc/book/src/Qpid-Management-Framework.xml

<?xml version="1.0" encoding="utf-8"?>
<!--
 
 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.
 
-->

<section><title>
      Qpid Management Framework
    </title>
            <itemizedlist>
              <listitem><para>
                <xref linkend="QpidManagementFramework-WhatIsQMF"/>
              </para></listitem>
              <listitem><para>
                <xref linkend="QpidManagementFramework-GettingStartedwithQMF"/>
              </para></listitem>
              <listitem><para>
                <xref linkend="QpidManagementFramework-QMFConcepts"/>
              </para></listitem>
              <listitem><para>
                <itemizedlist>
                  <listitem><para>
                    <xref linkend="QpidManagementFramework-Console-2CAgent-2CandBroker"/>
                  </para></listitem>
                  <listitem><para>
                    <xref linkend="QpidManagementFramework-Schema"/>
                  </para></listitem>
                  <listitem><para>
                    <xref linkend="QpidManagementFramework-ClassKeysandClassVersioning"/>
                  </para></listitem>
                </itemizedlist>
              </para></listitem>
              <listitem><para>
                <xref linkend="QpidManagementFramework-TheQMFProtocol"/>
              </para></listitem>
              <listitem><para>
                <xref linkend="QpidManagementFramework-HowtoWriteaQMFConsole"/>
              </para></listitem>
              <listitem><para>
                <xref linkend="QpidManagementFramework-HowtoWriteaQMFAgent"/>
              </para></listitem>
            </itemizedlist>
          
            <para>
              Please visit the <xref linkend="qpid_QMFv2-Project-Page"/> for information
              about the future of QMF.
            </para>
          <section role="h1" id="QpidManagementFramework-WhatIsQMF"><title>
            What Is QMF
          </title>

	 <para>
            QMF (Qpid Management Framework) is a general-purpose management
            bus built on Qpid Messaging. It takes advantage of the
            scalability, security, and rich capabilities of Qpid to provide
            flexible and easy-to-use manageability to a large set of
            applications.
          </para>
	  <!--h1--></section>

	  <section role="h1" id="QpidManagementFramework-GettingStartedwithQMF"><title>
            Getting
            Started with QMF
          </title>

	 <para>
            QMF is used through two primary APIs. The <emphasis>console</emphasis> API is
            used for console applications that wish to access and manipulate
            manageable components through QMF. The <emphasis>agent</emphasis> API is used
            for application that wish to be managed through QMF.
          </para><para>
            The fastest way to get started with QMF is to work through the
            "How To" tutorials for consoles and agents. For a deeper
            understanding of what is happening in the tutorials, it is
            recommended that you look at the <emphasis>Qmf Concepts</emphasis> section.
          </para>
	  <!--h1--></section>

	  <section role="h1" id="QpidManagementFramework-QMFConcepts"><title>
            QMF Concepts
          </title>

	 <para>
            This section introduces important concepts underlying QMF.
          </para>


	  <section role="h2" id="QpidManagementFramework-Console-2CAgent-2CandBroker"><title>
            Console,
            Agent, and Broker
          </title>

	 <para>
            The major architectural components of QMF are the Console, the
            Agent, and the Broker. Console components are the "managing"
            components of QMF and agent components are the "managed" parts.
            The broker is a central (possibly distributed, clustered and
            fault-tolerant) component that manages name spaces and caches
            schema information.
          </para><para>
            A console application may be a command-line utility, a
            three-tiered web-based GUI, a collection and storage device, a
            specialized application that monitors and reacts to events and
            conditions, or anything else somebody wishes to develop that uses
            QMF management data.
          </para><para>
            An agent application is any application that has been enhanced to
            allow itself to be managed via QMF.
          </para>
            <programlisting>
       +-------------+    +---------+    +---------------+    +-------------------+
       | CLI utility |    | Web app |    | Audit storage |    | Event correlation |
       +-------------+    +---------+    +---------------+    +-------------------+
              ^                ^                 ^                ^          |
              |                |                 |                |          |
              v                v                 v                v          v
    +---------------------------------------------------------------------------------+
    |                Qpid Messaging Bus (with QMF Broker capability)                  |
    +---------------------------------------------------------------------------------+
                    ^                     ^                     ^
                    |                     |                     |
                    v                     v                     v
           +----------------+    +----------------+    +----------------+
           | Manageable app |    | Manageable app |    | Manageable app |
           +----------------+    +----------------+    +----------------+
</programlisting>
          <para>
            In the above diagram, the <emphasis>Manageable apps</emphasis> are agents,
            the <emphasis>CLI utility</emphasis>, <emphasis>Web app</emphasis>, and <emphasis>Audit
            storage</emphasis> are consoles, and <emphasis>Event correlation</emphasis> is both
            a console and an agent because it can create events based on the
            aggregation of what it sees.
          </para>
<!--h2--></section>

	  <section role="h2" id="QpidManagementFramework-Schema"><title>
            Schema
          </title>
	 
	  <para>
            A <emphasis>schema</emphasis> describes the structure of management data.
            Each <emphasis>agent</emphasis> provides a schema that describes its
            management model including the object classes, methods, events,
            etc. that it provides. In the current QMF distribution, the
            agent's schema is codified in an XML document. In the near
            future, there will also be ways to programatically create QMF
            schemata.
          </para><section role="h3" id="QpidManagementFramework-Package"><title>
            Package
          </title>

	 <para>
            Each agent that exports a schema identifies itself using a
            <emphasis>package</emphasis> name. The package provides a unique namespace
            for the classes in the agent's schema that prevent collisions
            with identically named classes in other agents' schemata.
          </para><para>
            Package names are in "reverse domain name" form with levels of
            hierarchy separated by periods. For example, the Qpid messaging
            broker uses package "org.apache.qpid.broker" and the Access
            Control List plugin for the broker uses package
            "org.apache.qpid.acl". In general, the package name should be the
            reverse of the internet domain name assigned to the organization
            that owns the agent software followed by identifiers to uniquely
            identify the agent.
          </para><para>
            The XML document for a package's schema uses an enclosing
            &lt;schema&gt; tag. For example:
          </para>
            <programlisting>
&lt;schema package="org.apache.qpid.broker"&gt;

&lt;/schema&gt;
</programlisting>
<!--h3--></section>

          <section role="h3" id="QpidManagementFramework-ObjectClasses"><title>
            Object
            Classes
          </title>

	 <para>
            <emphasis>Object classes</emphasis> define types for manageable objects. The
            agent may create and destroy objects which are instances of
            object classes in the schema. An object class is defined in the
            XML document using the &lt;class&gt; tag. An object class is
            composed of properties, statistics, and methods.
          </para>
            <programlisting>
  &lt;class name="Exchange"&gt;
    &lt;property name="vhostRef"   type="objId" references="Vhost" access="RC" index="y" parentRef="y"/&gt;
    &lt;property name="name"       type="sstr"  access="RC" index="y"/&gt;
    &lt;property name="type"       type="sstr"  access="RO"/&gt;
    &lt;property name="durable"    type="bool"  access="RC"/&gt;
    &lt;property name="arguments"  type="map"   access="RO" desc="Arguments supplied in exchange.declare"/&gt;

    &lt;statistic name="producerCount" type="hilo32"  desc="Current producers on exchange"/&gt;
    &lt;statistic name="bindingCount"  type="hilo32"  desc="Current bindings"/&gt;
    &lt;statistic name="msgReceives"   type="count64" desc="Total messages received"/&gt;
    &lt;statistic name="msgDrops"      type="count64" desc="Total messages dropped (no matching key)"/&gt;
    &lt;statistic name="msgRoutes"     type="count64" desc="Total routed messages"/&gt;
    &lt;statistic name="byteReceives"  type="count64" desc="Total bytes received"/&gt;
    &lt;statistic name="byteDrops"     type="count64" desc="Total bytes dropped (no matching key)"/&gt;
    &lt;statistic name="byteRoutes"    type="count64" desc="Total routed bytes"/&gt;
  &lt;/class&gt;
</programlisting>
<!--h3--></section>


          <section role="h3" id="QpidManagementFramework-PropertiesandStatistics"><title>
            Properties
            and Statistics
          </title>

	 <para>
            &lt;property&gt; and &lt;statistic&gt; tags must be placed within
            &lt;schema&gt; and &lt;/schema&gt; tags.
          </para><para>
            Properties, statistics, and methods are the building blocks of an
            object class. Properties and statistics are both object
            attributes, though they are treated differently. If an object
            attribute is defining, seldom or never changes, or is large in
            size, it should be defined as a <emphasis>property</emphasis>. If an
            attribute is rapidly changing or is used to instrument the object
            (counters, etc.), it should be defined as a <emphasis>statistic</emphasis>.
          </para><para>
            The XML syntax for &lt;property&gt; and &lt;statistic&gt; have
            the following XML-attributes:
          </para><table><title>XML Attributes for QMF Properties and Statistics</title><tgroup cols="4">
            <tbody>
              <row>
                <entry>
                  Attribute
                </entry>
                <entry>
                  &lt;property&gt;
                </entry>
                <entry>
                  &lt;statistic&gt;
                </entry>
                <entry>
                  Meaning
                </entry>
              </row>
              <row>
                <entry>
                  name
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                  The name of the attribute
                </entry>
              </row>
              <row>
                <entry>
                  type
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                  The data type of the attribute
                </entry>
              </row>
              <row>
                <entry>
                  unit
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                  Optional unit name - use the singular (i.e. MByte)
                </entry>
              </row>
              <row>
                <entry>
                  desc
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                  Description to annotate the attribute
                </entry>
              </row>
              <row>
                <entry>
                  references
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                   
                </entry>
                <entry>
                  If the type is "objId", names the referenced class
                </entry>
              </row>
              <row>
                <entry>
                  access
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                   
                </entry>
                <entry>
                  Access rights (RC, RW, RO)
                </entry>
              </row>
              <row>
                <entry>
                  index
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                   
                </entry>
                <entry>
                  "y" if this property is used to uniquely identify the
                  object. There may be more than one index property in a
                  class
                </entry>
              </row>
              <row>
                <entry>
                  parentRef
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                   
                </entry>
                <entry>
                  "y" if this property references an object in which this
                  object is in a child-parent relationship.
                </entry>
              </row>
              <row>
                <entry>
                  optional
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                   
                </entry>
                <entry>
                  "y" if this property is optional (i.e. may be
                  NULL/not-present)
                </entry>
              </row>
              <row>
                <entry>
                  min
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                   
                </entry>
                <entry>
                  Minimum value of a numeric attribute
                </entry>
              </row>
              <row>
                <entry>
                  max
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                   
                </entry>
                <entry>
                  Maximum value of a numeric attribute
                </entry>
              </row>
              <row>
                <entry>
                  maxLen
                </entry>
                <entry>
                  Y
                </entry>
                <entry>
                   
                </entry>
                <entry>
                  Maximum length of a string attribute
                </entry>
              </row>
            </tbody>
          </tgroup></table>
<!--h3--></section>


	  <section role="h3" id="QpidManagementFramework-Methods"><title>
            Methods
          </title>

	 <para>
            &lt;method&gt; tags must be placed within &lt;schema&gt; and
            &lt;/schema&gt; tags.
          </para><para>
            A <emphasis>method</emphasis> is an invokable function to be performed on
            instances of the object class (i.e. a Remote Procedure Call). A
            &lt;method&gt; tag has a name, an optional description, and
            encloses zero or more arguments. Method arguments are defined by
            the &lt;arg&gt; tag and have a name, a type, a direction, and an
            optional description. The argument direction can be "I", "O", or
            "IO" indicating input, output, and input/output respectively. An
            example:
          </para>
            <programlisting>
   &lt;method name="echo" desc="Request a response to test the path to the management broker"&gt;
     &lt;arg name="sequence" dir="IO" type="uint32"/&gt;
     &lt;arg name="body"     dir="IO" type="lstr"/&gt;
   &lt;/method&gt;
</programlisting>
<!--h3--></section>

          <section role="h3" id="QpidManagementFramework-EventClasses"><title>
            Event Classes
          </title>
	  <para/>
	  <!--h3--></section>

	 <section role="h3" id="QpidManagementFramework-DataTypes"><title>
            Data Types
          </title>

	 <para>
            Object attributes, method arguments, and event arguments have
            data types. The data types are based on the rich data typing
            system provided by the AMQP messaging protocol. The following
            table describes the data types available for QMF:
          </para><table><title>QMF Datatypes</title><tgroup cols="2">
            <tbody>
              <row>
                <entry>
                  QMF Type
                </entry>
                <entry>
                  Description
                </entry>
              </row>
              <row>
                <entry>
                  REF
                </entry>
                <entry>
                  QMF Object ID - Used to reference another QMF object.
                </entry>
              </row>
              <row>
                <entry>
                  U8
                </entry>
                <entry>
                  8-bit unsigned integer
                </entry>
              </row>
              <row>
                <entry>
                  U16
                </entry>
                <entry>
                  16-bit unsigned integer
                </entry>
              </row>
              <row>
                <entry>
                  U32
                </entry>
                <entry>
                  32-bit unsigned integer
                </entry>
              </row>
              <row>
                <entry>
                  U64
                </entry>
                <entry>
                  64-bit unsigned integer
                </entry>
              </row>
              <row>
                <entry>
                  S8
                </entry>
                <entry>
                  8-bit signed integer
                </entry>
              </row>
              <row>
                <entry>
                  S16
                </entry>
                <entry>
                  16-bit signed integer
                </entry>
              </row>
              <row>
                <entry>
                  S32
                </entry>
                <entry>
                  32-bit signed integer
                </entry>
              </row>
              <row>
                <entry>
                  S64
                </entry>
                <entry>
                  64-bit signed integer
                </entry>
              </row>
              <row>
                <entry>
                  BOOL
                </entry>
                <entry>
                  Boolean - True or False
                </entry>
              </row>
              <row>
                <entry>
                  SSTR
                </entry>
                <entry>
                  Short String - String of up to 255 bytes
                </entry>
              </row>
              <row>
                <entry>
                  LSTR
                </entry>
                <entry>
                  Long String - String of up to 65535 bytes
                </entry>
              </row>
              <row>
                <entry>
                  ABSTIME
                </entry>
                <entry>
                  Absolute time since the epoch in nanoseconds (64-bits)
                </entry>
              </row>
              <row>
                <entry>
                  DELTATIME
                </entry>
                <entry>
                  Delta time in nanoseconds (64-bits)
                </entry>
              </row>
              <row>
                <entry>
                  FLOAT
                </entry>
                <entry>
                  Single precision floating point number
                </entry>
              </row>
              <row>
                <entry>
                  DOUBLE
                </entry>
                <entry>
                  Double precision floating point number
                </entry>
              </row>
              <row>
                <entry>
                  UUID
                </entry>
                <entry>
                  UUID - 128 bits
                </entry>
              </row>
              <row>
                <entry>
                  FTABLE
                </entry>
                <entry>
                  Field-table - std::map in C++, dictionary in Python
                </entry>
              </row>
            </tbody>
          </tgroup></table><para>
            In the XML schema definition, types go by different names and
            there are a number of special cases. This is because the XML
            schema is used in code-generation for the agent API. It provides
            options that control what kind of accessors are generated for
            attributes of different types. The following table enumerates the
            types available in the XML format, which QMF types they map to,
            and other special handling that occurs.
          </para><table><title>XML Schema Mapping for QMF Types</title><tgroup cols="4">
            <tbody>
              <row>
                <entry>
                  XML Type
                </entry>
                <entry>
                  QMF Type
                </entry>
                <entry>
                  Accessor Style
                </entry>
                <entry>
                  Special Characteristics
                </entry>
              </row>
              <row>
                <entry>
                  objId
                </entry>
                <entry>
                  REF
                </entry>
                <entry>
                  Direct (get, set)
                </entry>
                <entry>
                   
                </entry>
              </row>
              <row>
                <entry>
                  uint8,16,32,64
                </entry>
                <entry>
                  U8,16,32,64
                </entry>
                <entry>
                  Direct (get, set)
                </entry>
                <entry>
                   
                </entry>
              </row>
              <row>
                <entry>
                  int8,16,32,64
                </entry>
                <entry>
                  S8,16,32,64
                </entry>
                <entry>
                  Direct (get, set)
                </entry>
                <entry>
                   
                </entry>
              </row>
              <row>
                <entry>
                  bool
                </entry>
                <entry>
                  BOOL
                </entry>
                <entry>
                  Direct (get, set)
                </entry>
                <entry>
                   
                </entry>
              </row>
              <row>
                <entry>
                  sstr
                </entry>
                <entry>
                  SSTR
                </entry>
                <entry>
                  Direct (get, set)
                </entry>
                <entry>
                   
                </entry>
              </row>
              <row>
                <entry>
                  lstr
                </entry>
                <entry>
                  LSTR
                </entry>
                <entry>
                  Direct (get, set)
                </entry>
                <entry>
                   
                </entry>
              </row>
              <row>
                <entry>
                  absTime
                </entry>
                <entry>
                  ABSTIME
                </entry>
                <entry>
                  Direct (get, set)
                </entry>
                <entry>
                   
                </entry>
              </row>
              <row>
                <entry>
                  deltaTime
                </entry>
                <entry>
                  DELTATIME
                </entry>
                <entry>
                  Direct (get, set)
                </entry>
                <entry>
                   
                </entry>
              </row>
              <row>
                <entry>
                  float
                </entry>
                <entry>
                  FLOAT
                </entry>
                <entry>
                  Direct (get, set)
                </entry>
                <entry>
                   
                </entry>
              </row>
              <row>
                <entry>
                  double
                </entry>
                <entry>
                  DOUBLE
                </entry>
                <entry>
                  Direct (get, set)
                </entry>
                <entry>
                   
                </entry>
              </row>
              <row>
                <entry>
                  uuid
                </entry>
                <entry>
                  UUID
                </entry>
                <entry>
                  Direct (get, set)
                </entry>
                <entry>
                   
                </entry>
              </row>
              <row>
                <entry>
                  map
                </entry>
                <entry>
                  FTABLE
                </entry>
                <entry>
                  Direct (get, set)
                </entry>
                <entry>
                   
                </entry>
              </row>
              <row>
                <entry>
                  hilo8,16,32,64
                </entry>
                <entry>
                  U8,16,32,64
                </entry>
                <entry>
                  Counter (inc, dec)
                </entry>
                <entry>
                  Generates value, valueMin, valueMax
                </entry>
              </row>
              <row>
                <entry>
                  count8,16,32,64
                </entry>
                <entry>
                  U8,16,32,64
                </entry>
                <entry>
                  Counter (inc, dec)
                </entry>
                <entry>
                   
                </entry>
              </row>
              <row>
                <entry>
                  mma32,64
                </entry>
                <entry>
                  U32,64
                </entry>
                <entry>
                  Direct
                </entry>
                <entry>
                  Generates valueMin, valueMax, valueAverage, valueSamples
                </entry>
              </row>
              <row>
                <entry>
                  mmaTime
                </entry>
                <entry>
                  DELTATIME
                </entry>
                <entry>
                  Direct
                </entry>
                <entry>
                  Generates valueMin, valueMax, valueAverage, valueSamples
                </entry>
              </row>
            </tbody>
          </tgroup></table>

	  <note><title>Important</title>
                  <para>
                    When writing a schema using the XML format, types used in
                    &lt;property&gt; or &lt;arg&gt; must be types that have
                    <emphasis>Direct</emphasis> accessor style. Any type may be used in
                    &lt;statistic&gt; tags.
                  </para>
	  </note>

<!--h3--></section>
<!--h2--></section>

          <section role="h2" id="QpidManagementFramework-ClassKeysandClassVersioning"><title>
            Class
            Keys and Class Versioning
          </title>

	  <para/>

<!--h2--></section>

	<!--h1--></section>

	 <section role="h1" id="QpidManagementFramework-TheQMFProtocol"><title>
            The QMF
            Protocol
          </title>

	 <para>
            The QMF protocol defines the message formats and communication
            patterns used by the different QMF components to communicate with
            one another.
          </para><para>
            A description of the current version of the QMF protocol can be
            found at <xref linkend="qpid_QMF-Protocol"/>.
          </para><para>
            A proposal for an updated protocol based on map-messages is in
            progress and can be found at <xref linkend="qpid_QMF-Map-Message-Protocol"/>.
          </para>
<!--h1--></section>

	  <section role="h1" id="QpidManagementFramework-HowtoWriteaQMFConsole"><title>
            How
            to Write a QMF Console
          </title>

	 <para>
            Please see the <xref linkend="qpid_QMF-Python-Console-Tutorial"/> for information about using the console API with
            Python.
          </para>
<!--h1--></section>

	  <section role="h1" id="QpidManagementFramework-HowtoWriteaQMFAgent"><title>
            How to
            Write a QMF Agent
          </title>
	  <para/>
	  <!--h1--></section>

	 
</section>