| <?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 |
| <schema> tag. For example: |
| </para> |
| <programlisting> |
| <schema package="org.apache.qpid.broker"> |
| |
| </schema> |
| </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 <class> tag. An object class is |
| composed of properties, statistics, and methods. |
| </para> |
| <programlisting> |
| <class name="Exchange"> |
| <property name="vhostRef" type="objId" references="Vhost" access="RC" index="y" parentRef="y"/> |
| <property name="name" type="sstr" access="RC" index="y"/> |
| <property name="type" type="sstr" access="RO"/> |
| <property name="durable" type="bool" access="RC"/> |
| <property name="arguments" type="map" access="RO" desc="Arguments supplied in exchange.declare"/> |
| |
| <statistic name="producerCount" type="hilo32" desc="Current producers on exchange"/> |
| <statistic name="bindingCount" type="hilo32" desc="Current bindings"/> |
| <statistic name="msgReceives" type="count64" desc="Total messages received"/> |
| <statistic name="msgDrops" type="count64" desc="Total messages dropped (no matching key)"/> |
| <statistic name="msgRoutes" type="count64" desc="Total routed messages"/> |
| <statistic name="byteReceives" type="count64" desc="Total bytes received"/> |
| <statistic name="byteDrops" type="count64" desc="Total bytes dropped (no matching key)"/> |
| <statistic name="byteRoutes" type="count64" desc="Total routed bytes"/> |
| </class> |
| </programlisting> |
| <!--h3--></section> |
| |
| |
| <section role="h3" id="QpidManagementFramework-PropertiesandStatistics"><title> |
| Properties |
| and Statistics |
| </title> |
| |
| <para> |
| <property> and <statistic> tags must be placed within |
| <schema> and </schema> 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 <property> and <statistic> 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> |
| <property> |
| </entry> |
| <entry> |
| <statistic> |
| </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> |
| <method> tags must be placed within <schema> and |
| </schema> 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 |
| <method> tag has a name, an optional description, and |
| encloses zero or more arguments. Method arguments are defined by |
| the <arg> 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> |
| <method name="echo" desc="Request a response to test the path to the management broker"> |
| <arg name="sequence" dir="IO" type="uint32"/> |
| <arg name="body" dir="IO" type="lstr"/> |
| </method> |
| </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 |
| <property> or <arg> must be types that have |
| <emphasis>Direct</emphasis> accessor style. Any type may be used in |
| <statistic> 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> |
