THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
| Info | ||
|---|---|---|
| ||
This page is being updated with protocol changes introduced in M4 (and are unchanged in release 0.5) |
Protocol Header
The body segments of management QMF messages are composed of sequences of binary-encoded data fields, in a manner consistent with the 0-10 version of the AMQP specification.
All management QMF messages begin with a message header:
...
Communication is established between the management client and management agent using normal AMQP procedures. The client creates a connection to the broker and then establishes a session with its corresponding channel.
Two A private queues are then declared (only one if method invocation is not needed). A management queue is (exclusive/auto-delete) queue is then declared and bound to the qpid.management exchange. If the A binding with key is "mgmtschema.#" , will subscribe to all management-related messages sent to the exchange will be received by this client. A more specific binding key will result in a more restricted set of messages being received (see the section on Routing Key Structure below).schema-related information and a second binding with key "console.#" will subscribe to all management data.
A binding must also be established to the "amq.direct" exchange using the queue's name as the binding key. This will be used as a reply-to address for requests sent to the broker and to agents.If methods are going to be invoked on managed objects, a second private queue must be declared so the client can receive method replies. This queue is bound to the amq.direct exchange using a routing key equal to the name of the queue.
When a client successfully binds to the qpid.management exchange, the management agent schedules a schema broadcast to be sent to the exchange. The agent will publish, via the exchange, a description of the schema for all manageable objects in its control.
| No Format |
|---|
Client Broker
| |
| --- AMQP Connection and Session Setup -------------------------> |
| |
| --- Queue.declare (private data queue) ------------------------> |
| --- Bind queue to exchange 'qpid.management' key 'mgmtschema.#' ---> |
| --- Bind queue to exchange 'qpid.management' key 'console.#' --> |
| --- Bind queue to exchange 'amq.direct' -----------------------> |
| |
| --- Queue.declare (private method-reply queue) -------------> |
| --- Bind queue to exchange 'amq.direct' --------------------> |
| |
| --- Broker Request --------------------------------------------> |
| <------------------------------------------- Broker Response --- |
| |
| |
| |
| <---------- Management schema via exchange 'qpid.management' --- |
| |
|
Broadcast of Configuration and Instrumentation Updates
The management agent will periodically publish updates to the configuration and instrumentation of management objects under its control. Under normal circumstances, these updates are published only if they have changed since the last time they were published. Configuration updates are only published if configuration has changed and instrumentation updates are only published if instrumentation has changed. The exception to this rule is that after a management client binds to the qpid.management exchange, all configuration and instrumentation records are published as though they had changed whether or not they actually did.
| No Format |
|---|
Client Client Broker | | | | <--------------- | <--- Object properties via 'mgmt.*.prop.#console.obj.1.<agent-bank>.<package>.<class>' --- | | | <------------------ Object statistics via 'mgmt.*.stat.#console.obj.1.<agent-bank>.<package>.<class>' --- | | | | | | | | | | Publish Interval | | | | Interval | | | | | | | V | <--------------- V | <--- Object properties via 'mgmt.*.prop.#console.obj.1.<agent-bank>.<package>.<class>' --- | | <------------------ Object statistics via 'mgmt.*.stat.#console.obj.1.<agent-bank>.<package>.<class>' --- | | | | |
Invoking a Method on a Managed Object
...
Details of QMF Message Types
opcode | message | handled by | description |
|---|---|---|---|
'B' | Broker Request | broker | This message contains a broker request, sent from the management console to the broker to initiate a management session. |
'b' | Broker Response | console | This message contains a broker response, sent from the broker in response to a broker request message. |
'z' | Command Completion | all | This message is sent to indicate the completion of a request. |
'Q' | Class Query | broker, agent | Class query messages are used by a management console to request a list of schema classes that are known by the management broker. |
'q' | Class Indication | console, broker | Sent by the management broker, a class indication notifies the peer of the existence of a schema class. |
'S' | Schema Request | broker, agent | Schema request messages are used to request the full schema details for a class. |
's' | Schema Response | console, broker | Schema response message contain a full description of the schema for a class. |
'h' | Heartbeat Indication | console | This message is published once per publish-interval. It can be used by a client to positively determine which objects did not change during the interval (since updates are not published for objects with no changes). |
'c', 'i', 'g' | Content Indication | console | This message contains a content record. Content records contain the values of all properties or statistics in an object. Such records are broadcast on a periodic interval if 1) a change has been made in the value of one of the elements, or 2) if a new management client has bound a queue to the management exchange. |
'e' | Event Indication | console | This message contains an event indication, sent by an agent to the topic exchange qpid.management. |
'G' | Get Query | agent | Sent by a management console, a get query requests that the management broker provide content indications for all objects that match the query criteria. |
'M' | Method Request | agent | This message contains a method request. |
'm' | Method Response | console | This message contains a method result. |
'P' | Package Query | broker, agent | This message contains a schema package query request, requesting that the broker dump the list of known packages |
'p' | Package Indication | console, broker | This message contains a schema package indication, identifying a package known by the broker |
'A' | Agent Attach Request | broker | This message is sent by a remote agent when it wishes to attach to a management broker |
'a' | Agent Attach Response | agent | The management broker sends this response if an attaching remote agent is permitted to join |
'x' | Console Added Indication | agent | This message is sent to all remote agents by the management broker when a new console binds to the management exchange |
...
When a management console first establishes contact with the broker, it sends a Broker Request message to initiate the exchange.
| No Format |
|---|
routing_key: broker
+-----+-----+-----+-----+-----------------------+
| 'A' | 'M' | '2' | 'B' | 0 |
+-----+-----+-----+-----+-----------------------+
|
...
When the broker receives a Broker Request message, it responds with a Broker Response message. This message contains an identifier unique to the broker.
| No Format |
|---|
routing_key: <reply_to from request>
+-----+-----+-----+-----+-----------------------+
| 'A' | 'M' | '2' | 'b' | 0 |
+-----+-----+-----+-----+-----------------------+----------------------------+
| brokerId (uuid) |
+----------------------------------------------------------------------------+
|
Command Completion Message
| No Format |
|---|
routing_key: <reply_to from request>
+-----+-----+-----+-----+-----------------------+
| 'A' | 'M' | '2' | 'z' | seq |
+-----+-----+-----+-----+----+------------------+
| Completion Code (uint32) |
+----------------------------+------------------------------------+
| Completion Text (str8) |
+-----------------------------------------------------------------+
|
Class Query
| No Format |
|---|
routing_key: broker
+-----+-----+-----+-----+-----------------------+
| 'A' | 'M' | '2' | 'Q' | seq |
+-----+-----+-----+-----+-----------------------+----------+
| package name (str8) |
+----------------------------------------------------------+
|
Class Indication
| No Format |
|---|
routing_key: <reply_to from request> (if in reply to +-----+-----+-----+-----+-a request) schema.package (if unsolicited) +-----+-----+-----+-----+-----------------------+ | 'A' | 'M' | '2' | 'q' | seq | +-----+-----+-----+-----+---------------+-------+ | class kind (uint8) 1=Object, 2=Event | +---------------------------------------+------------------+ | package name (str8) | +----------------------------------------------------------+ | class name (str8) | +----------------------------------------------------------+ | schema hash (bin128) | +----------------------------------------------------------+ |
Schema Request
| No Format |
|---|
routing_key: broker
+-----+-----+-----+-----+-----------------------+
| 'A' | 'M' | '2' | 'S' | seq |
+-----+-----+-----+-----+-----------------------+----------+
| packageName (str8) |
+----------------------------------------------------------+
| className (str8) |
+----------------------------------------------------------+
| schema-hash (bin128) |
+----------------------------------------------------------+
|
Schema Response
| No Format |
|---|
routing_key: <reply_to from request> (if in reply to +-----+-----+-----+-----+-a request) schema.package (if unsolicited) +-----+-----+-----+-----+-----------------------+ | 'A' | 'M' | '2' | 's' | seq | +-----+-----+-----+-----+------------+----------+ | kind (uint8) 1=Object, 2=Event | +------------------------------------+---------------------+ | packageName (str8) | +----------------------------------------------------------+ | className (str8) | +----------------------------------------------------------+ | schema-hash (bin128) | +-----------------------------------------------+----------+ | propCount (uint16) | +-----------------------------------------------+ | statCount (uint16) | +-----------------------------------------------+ | methodCount (uint16) | +-----------------------------------------------+----------------------------+ | propCount property records | +----------------------------------------------------------------------------+ | statCount statistic records | +----------------------------------------------------------------------------+ | methodCount method records | +----------------------------------------------------------------------------+ |
...
field name | optional | description |
|---|---|---|
name | no | Name of the property |
type | no | Type code for the property |
refPackage | yes | Name of referenced package (for objectReference and object types) |
refClass | yes | Name of referenced class (for objectReference and object types) |
access | no | Access code for the property |
index | no | 1 = index element, 0 = not an index element |
optional | no | 1 = optional element (may be not present), 0 = mandatory (always present) |
unit | yes | Units for numeric values (i.e. seconds, bytes, etc.) |
min | yes | Minimum value for numerics |
max | yes | Maximum value for numerics |
maxlen | yes | Maximum length for strings |
desc | yes | Description of the property |
...
field name | optional | description |
|---|---|---|
name | no | Argument name |
type | no | Type code for the argument |
refPackage | yes | Name of referenced package (for objectReference and object types) |
refClass | yes | Name of referenced class (for objectReference and object types) |
dir | yes | Direction code for method arguments |
unit | yes | Units for numeric values (i.e. seconds, bytes, etc.) |
min | yes | Minimum value for numerics |
max | yes | Maximum value for numerics |
maxlen | yes | Maximum length for strings |
desc | yes | Description of the argument |
default | yes | Default value for the argument |
type codes are numerics with the following values:
value | type | Encoding |
|---|---|---|
1 | uint8 | uint8 |
2 | uint16 | uint16 |
3 | uint32 | uint32 |
4 | uint64 | uint64 |
6 | str8 | str8 |
7 | str16 | str16 |
8 | absTime | (uint64) |
9 | deltaTime | (uint64) |
10 | objectReference | (bin128) |
11 | boolean | boolean(uint8) |
12 | float | float |
13 | double | double |
14 | uuid | uuid |
15 | map | map |
16 | int8 | int8 |
17 | int16 | int16 |
18 | int32 | int32 |
19 | int64 | int64 |
20 | object | package-name(str8) + class-name(str8) + hash(bin128) + object-indication-encoding |
21 | list | list |
22 | array | array |
access codes are numerics with the following values:
...
Heartbeat Indication
| No Format |
|---|
routing_key: console.heartbeat.1.<agent_bank>
+-----+-----+-----+-----+-----------------------+
| 'A' | 'M' | '2' | 'h' | 0 |
+-----+-----+-----+-----+-----------------------+
| timestamp of current interval (datetime) |
+-----------------------------------------------+
|
...
Content messages are published when changes are made to the values of properties or statistics or when new management clients bind a queue to the management exchange.
| No Format |
|---|
for 'g': +-----+-----+-----+routing_key: <reply_to from request> for 'c','i': routing_key: console.obj.1.<agent_bank>.<package_name>.<class_name> +-----+-----+-----+-------+-----------------------+ | 'A' | 'M' | '2' |'g/c/i'| seq | +-----+-----+-----+-------+-----------------------+--------+ | packageName (str8) | +----------------------------------------------------------+ | className (str8) | +----------------------------------------------------------+ | class hash (bin128) | +-----+-----+-----+-----+-----+-----+-----+-----+----------+ | timestamp of current sample (datetime) | +-----+-----+-----+-----+-----+-----+-----+-----+ | time object was created (datetime) | +-----+-----+-----+-----+-----+-----+-----+-----+ | time object was deleted (datetime) | +-----+-----+-----+-----+-----+-----+-----+-----+ | objectId (bin128) | +-----+-----+-----+-----+-----+-----+-----+-----+ | presence bitmasks (0 or more uint8 fields) | +-----+-----+-----+-----+-----+-----+-----+-----+------------------------+ | config/inst values (in schema order) | +------------------------------------------------------------------------+ |
...
The element values are encoded by their type into the message in the order in which they appeared in the schema message.the message in the order in which they appeared in the schema message.
Event Indication Message
| No Format |
|---|
routing_key: console.event.1.<agent_bank>.<package_name>.<event_name>
+-----+-----+-----+-----+-----------------------+
| 'A' | 'M' | '2' | 'e' | seq |
+-----+-----+-----+-----+-----------------------+----------+
| packageName (str8) |
+----------------------------------------------------------+
| eventName (str8) |
+----------------------------------------------------------+
| class hash (bin128) |
+-----------------------------------------------+----------+
| timestamp of event (datetime) |
+-----------------------+-----------------------+
| severity (uint8) |
+-----------------------+------------------------------------------------+
| event argument values (in schema order) |
+------------------------------------------------------------------------+
|
Get Query Message
A Get Request may be sent by the management console to cause a management agent to immediately send content information for objects of a class.
| No Format |
|---|
routing_key: agent.1.<agent_bank>
+-----+-----+-----+-----+-----------------------+
| 'A' | 'M' | '2' | 'G' | seq |
+-----+-----+-----+-----+-----------------------+----------+
| Get request field table (map) |
+----------------------------------------------------------+
|
...
Method request messages have the following structure. The sequence number is opaque to the management agent. It is returned unchanged in the method reply so the calling client can correctly associate the reply to the request. The objectId is the unique ID of the object on which the method is to be executed.
| No Format |
|---|
routing_key: agent.1.<agent_bank>
+-----+-----+-----+-----+-----------------------+
| 'A' | 'M' | '2' | 'M' | seq |
+-----+-----+-----+-----+-----------------------+
| objectId (bin128) |
+-----------------------------------------------+
| package name (str8) |
+-----------------------------------------------+
| class name (str8) |
+-----------------------------------------------+
| class hash (bin128) |
+-----------------------------------------------+
| methodName (str8) |
+-----------------------------------------------+------------------------+
| input and bidirectional argument values (in schema order) |
+------------------------------------------------------------------------+
|
...
Method reply messages have the following structure. The sequence number is identical to that supplied in the method request. The status code (and text) indicate whether or not the method was successful and if not, what the error was. Output and bidirectional arguments are only included if the status code was 0 (STATUS_OK).
| No Format |
|---|
routing_key: <reply_to from request>
+-----+-----+-----+-----+-----------------------+
| 'A' | 'M' | '2' | 'm' | seq |
+-----+-----+-----+-----+-----------------------+
| status code (uint32) |
+-----------------------+----------------------------------+
| status text (str16) |
+-----------------------+----------------------------------+-------------+
| output and bidirectional argument values (in schema order) |
+------------------------------------------------------------------------+
|
...
value | description |
|---|---|
0 | STATUS_OK - successful completion |
1 | STATUS_UNKNOWN_OBJECT - objectId not found in the agent |
2 | STATUS_UNKNOWN_METHOD - method is not known by the object type |
3 | STATUS_NOT_IMPLEMENTED - method is not currently implemented |
4 | STATUS_INVALID_PARAMETER - input argument is invalid |
5 | STATUS_FEATURE_NOT_IMPLEMENTED |
6 | STATUS_FORBIDDEN - operation is forbidden by Access Control List |
7 | STATUS_EXCEPTION - exception caught during method execution |
8 | STATUS_UNKNOWN_PACKAGE - package name not found |
9 | STATUS_UNKNOWN_CLASS - class name not found in package |
Messages for Extended Scenario
...
| No Format |
|---|
Broker Remote Agent
| |
| <----------------------------------------- Attach Request --- |
| --- Attach Response ----------------------------------------> |
| |
| <------------------------------------- Package Indication --- |
| <------------------------------------- Package Indication --- |
| |
| <--------------------------------------- Class Indication --- |
| <--------------------------------------- Class Indication --- |
| <--------------------------------------- Class Indication --- |
| <--------------------------------------- Class Indication --- |
| <--------------------------------------- Class Indication --- |
| |
| --- Schema Request (class key) -----------------------------> |
| <---------------------------------------- Schema Response --- |
| |
| --- Schema Request (class key) -----------------------------> |
| <---------------------------------------- Schema Response --- |
| |
| |
|
Package Query
Package Query
| No Format |
|---|
routing_key: agent.1.<agent_bank> |
| No Format |
+-----+-----+-----+-----+-----------------------+
| 'A' | 'M' | '2' | 'P' | seq |
+-----+-----+-----+-----+-----------------------+
|
Package Indication
| No Format |
|---|
routing_key: <reply_to from request> (if in reply to a request) schema.package (if unsolicited) +-----+-----+-----+-----+-----------------------+ | 'A' | 'M' | '2' | 'p' | seq | +-----+-----+-----+-----+-----------------------+----------+ | package name (str8) | +----------------------------------------------------------+ |
Agent Attach Request
| No Format |
|---|
routing_key: broker
+-----+-----+-----+-----+-----------------------+
| 'A' | 'M' | '2' | 'A' | seq |
+-----+-----+-----+-----+-----------------------+----------+
| label (str8) |
+----------------------------------------------------------+
| system-id (uuid) |
+---------------------------------+------------------------+
| requested broker bank (uint32) |
+---------------------------------+
| requested agent bank (uint32) |
+---------------------------------+
|
Agent Attach Response (success)
| No Format |
|---|
routing_key: <reply_to from request>
+-----+-----+-----+-----+-----------------------+
| 'A' | 'M' | '2' | 'a' | seq |
+-----+-----+-----+-----+--------+--------------+
| assigned broker bank (uint32) |
+--------------------------------+
| assigned agent bank (uint32) |
+--------------------------------+
|
Console Added Indication
| No Format |
|---|
routing_key: agent.1.<agent_bank>
+-----+-----+-----+-----+-----------------------+
| 'A' | 'M' | '2' | 'x' | seq |
+-----+-----+-----+-----+-----------------------+
|