[CONF] Apache Qpid: Qpid Management Framework (page edited)

[confluence]

Page Edited : qpid : Qpid Management Framework Qpid Management Framework has been edited by Ted Ross (Mar 05, 2009). Change summary: Added link to the protocol description (View changes) Content: What Is QMF Getting Started with QMF QMF Concepts Console, Agent, and Broker Schema Object Identifiers Class Keys and Class Versioning The QMF Protocol How to Write a QMF Console How to Write a QMF Agent What Is QMF 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. Getting Started with QMF QMF is used through two primary APIs. The console API is used for console applications that wish to access and manipulate manageable components through QMF. The agent API is used for application that wish to be managed through QMF. 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 Qmf Concepts section. QMF Concepts This section introduces important concepts underlying QMF. Console, Agent, and Broker 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. 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. An agent application is any application that has been enhanced to allow itself to be managed via QMF. +-------------+ +---------+ +---------------+ +-------------------+ | 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 | +----------------+ +----------------+ +----------------+ In the above diagram, the Manageable apps are agents, the CLI utility, Web app, and Audit storage are consoles, and Event correlation is both a console and an agent because it can create events based on the aggregation of what it sees. Schema A schema describes the structure of management data. Each agent 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. Package Each agent that exports a schema identifies itself using a package 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. 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. The XML document for a package's schema uses an enclosing <schema> tag. For example: <schema package="org.apache.qpid.broker"> </schema> Object Classes Object classes 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. <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> Properties and Statistics <property> and <statistic> tags must be placed within <schema> and </schema> tags. 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 property. If an attribute is rapidly changing or is used to instrument the object (counters, etc.), it should be defined as a statistic. The XML syntax for <property> and <statistic> have the following XML-attributes: Attribute <property> <statistic> Meaning name Y Y The name of the attribute type Y Y The data type of the attribute unit Y Y Optional unit name - use the singular (i.e. MByte) desc Y Y Description to annotate the attribute references Y   If the type is "objId", names the referenced class access Y   Access rights (RC, RW, RO) index Y   "y" if this property is used to uniquely identify the object. There may be more than one index property in a class parentRef Y   "y" if this property references an object in which this object is in a child-parent relationship. optional Y   "y" if this property is optional (i.e. may be NULL/not-present) min Y   Minimum value of a numeric attribute max Y   Maximum value of a numeric attribute maxLen Y   Maximum length of a string attribute Methods <method> tags must be placed within <schema> and </schema> tags. A method 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: <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> Event Classes Data Types 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: QMF Type Description REF QMF Object ID - Used to reference another QMF object. U8 8-bit unsigned integer U16 16-bit unsigned integer U32 32-bit unsigned integer U64 64-bit unsigned integer S8 8-bit signed integer S16 16-bit signed integer S32 32-bit signed integer S64 64-bit signed integer BOOL Boolean - True or False SSTR Short String - String of up to 255 bytes LSTR Long String - String of up to 65535 bytes ABSTIME Absolute time since the epoch in nanoseconds (64-bits) DELTATIME Delta time in nanoseconds (64-bits) FLOAT Single precision floating point number DOUBLE Double precision floating point number UUID UUID - 128 bits FTABLE Field-table - std::map in C++, dictionary in Python 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. XML Type QMF Type Accessor Style Special Characteristics objId REF Direct (get, set)   uint8,16,32,64 U8,16,32,64 Direct (get, set)   int8,16,32,64 S8,16,32,64 Direct (get, set)   bool BOOL Direct (get, set)   sstr SSTR Direct (get, set)   lstr LSTR Direct (get, set)   absTime ABSTIME Direct (get, set)   deltaTime DELTATIME Direct (get, set)   float FLOAT Direct (get, set)   double DOUBLE Direct (get, set)   uuid UUID Direct (get, set)   map FTABLE Direct (get, set)   hilo8,16,32,64 U8,16,32,64 Counter (inc, dec) Generates value, valueMin, valueMax count8,16,32,64 U8,16,32,64 Counter (inc, dec)   mma32,64 U32,64 Direct Generates valueMin, valueMax, valueAverage, valueSamples mmaTime DELTATIME Direct Generates valueMin, valueMax, valueAverage, valueSamples Important When writing a schema using the XML format, types used in <property> or <arg> must be types that have Direct accessor style. Any type may be used in <statistic> tags. Object Identifiers Every object, or instance of an object class, managed by QMF is assigned a unique object ID. The object ID is a structured 128-bit field. The bits of the object ID are laid out as follows: first uint_64: 63 60 59 48 47 28 27 0 +-------+------------+--------------------+----------------------------+ | flags | sequence | broker bank | agent bank | +-------+------------+--------------------+----------------------------+ second uint_64: 63 0 +----------------------------------------------------------------------+ | object number | +----------------------------------------------------------------------+ Object Id Fields: Field Name Size (bits) Description flags 4 Flags bits - all reserved (must be zero) sequence 12 Agent Restart Sequence - For persistent objects, this value must be zero. For transient objects, this value is a the restart sequence of the agent. broker bank 20 Bank number of assigning broker agent bank 28 Bank number of assigning agent object number 64 Number assigned to the object Class Keys and Class Versioning The QMF Protocol The QMF protocol defines the message formats and communication patterns used by the different QMF components to communicate with one another. A description of the current version of the QMF protocol can be found at QMF Protocol. How to Write a QMF Console Please see the QMF Python Console Tutorial for information about using the console API with Python. How to Write a QMF Agent

Powered by Atlassian Confluence (Version: 2.2.9 Build:#527 Sep 07, 2006) - Bug/feature request

Unsubscribe or edit your notifications preferences

--------------------------------------------------------------------- Apache Qpid - AMQP Messaging Implementation Project: http://qpid.apache.org Use/Interact: mailto:commits-subscr...@qpid.apache.org