diff options
Diffstat (limited to 'qpid/doc/book/src/cpp-broker/Qpid-Management-Framework.xml')
| -rw-r--r-- | qpid/doc/book/src/cpp-broker/Qpid-Management-Framework.xml | 944 |
1 files changed, 944 insertions, 0 deletions
diff --git a/qpid/doc/book/src/cpp-broker/Qpid-Management-Framework.xml b/qpid/doc/book/src/cpp-broker/Qpid-Management-Framework.xml new file mode 100644 index 0000000000..89bfe9d95e --- /dev/null +++ b/qpid/doc/book/src/cpp-broker/Qpid-Management-Framework.xml @@ -0,0 +1,944 @@ +<?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> |