Grid Publisher Specification

Introduction

The purpose of this document is to describe the specification of the monitoring information publishing layer that uses JMS standard (with OpenWire and STOMP protocols for cross-language compatibility) and ActiveMQ as the message broker.

Message format

All messages exchanged by the system should be valid JMS or STOMP messages. This specification describes the required header attributes and their semantics and recommends a standard message body format.

Message header

The following table defines standard message header attributes:

Attribute	Required?	Meaning
messageClass	Required	Message class name. Defines message body format and required in-message attributes
recordCount	Optional	If present, bulk-publishing indicator that defines a number of record published in the message
<in-message attribute>+	Optional	One or more attributes from the message body to enable selectors

Message body

We recommend using plain-text message body that is formed according to the grammar defined in GridMonitoringProbeSpecification#Message_Formats. If bulk publishing is not used (one data record per message) the record separator ("EOT" string) can be skipped. If bulk publishing is used the message body should contain exact number of records separated by "EOT" line as indicated by "recordCount" attribute. It that case the message body can look like this:

attribute1: value1
attribute2: value2
...
EOT
attribute1: value2
....

Message classes

For the purpose of GridMonitoringProbeSpecification we define the following message classes

• org.wlcg.metricDescription - attributes exactly as in GridMonitoringProbeSpecification#l_Listing_metrics_that_a_probe_r
• org.wlcg.metricOutput - attributes exactly as in GridMonitoringProbeSpecification#Probe_output_Format and in addition an optional attribute metricEnvironmentUUID (see below)
• org.wlcg.metricEnvironment - additional class which is optional and not defined in GridMonitoringProbeSpecification (see below)

org.wlcg.metricEnvironment is an additional class that is used by some of the monitoring systems (for example SAM) to provide additional information about the probe's environment at the time of probe execution, common to a number of results, and to bind the results with a single "probe execution session". The class defines the following attributes:

Attribute	Meaning
UUID	UUID string that uniquely identifies the environment
name	Name of the environment parameter (for example submitterDN)
value	Value of the parameter

Destinations

We suggest using JMS topics (/topic/...) as the destinations for all messages. In addition we recommend to prefix each topic name with the indicator of a scope, as one of the following:

• /topic/grid.* - messages on the grid level, that should be propagated to all parties (brokers in case of the network)
• /topic/region.* - regional messages, usually not propagated outside the region (ROC)
• /topic/site.* - site's internal fabric monitoring messages, usually not propagated indirectly outside the site (however can be republished to the grid level if needed)
• /topic/local.* - highly localised messages, limited to a single site's service, subsystem, cluster or even host.

For the purpose of GridMonitoringProbeSpecification we recommend using the following destination templates:

• /topic/scope.probe.metricOutput[.siteName] - default destination for all org.wlcg.metricOutput messages, with the optional . part for finer grained routing
• /topic/scope.probe.metricDescription - default destination for all org.wlcg.metricDescription messages
• /topic/scope.probe.metricEnvironment - default destination for all org.wlcg.metricEnvironment messages

Publishing client tool

Introduction

Publishing client tool is a simple command line utility that should meet the following criteria:

• portable across many platforms (preferably Python script using default libraries)
• allow publishing messages of many classes
• enforce required attributes of messages depending on the class
• highly configurable (broker connection, destinations per class, attributes per class, ...)
• reconfigurable by using command line switches

Input

All the input parameters and data should be passed as the command line arguments:

• -a header attributes - a list of attribute names (from the ones that appear in the data records according to the message class) to be included in the message header. Only single valued attributes should be used here. If the bulk publishing flag is set, the records should be aggregated in minimum number of messages, by the common values of header attributes.
• -b bulk publishing flag (default: yes) - if yes, then accumulate as much data records in one message as possible (limited by the header attributes, see below)
• -c alternative configuration file
• -d alternative message destination
• -g generic message class - publish even if message class is not defined, in that case there is no message validation (required attributes)
• messageClass - as a command line parameter
• data file(s) (or stdin if not provided) - as command line parameters, all the files should be text files with the message body format according to the provided messageClass

Configuration

The tool should look for its configuration file in the following locations:

• GRID_PUBLISHER_CONFIG - UNIX shell environment variable
• location pointed by -c command line option (overrides settings in GRID_PUBLISHER_CONFIG)

The configuration file should contain the following information:

• ActiveMQ broker contact URL
• default destination for messages
• supported message classes
• for each message class:
  • required attributes
  • attributes published in the message header (overridden by -a option)
  • default destination for that message class (if missing the general default destination is used)

Example:

[grid-publisher]
broker_url=stomp://lxb6117.cern.ch:61613
default_destination=/topic/grid.probe
messageClasses=org.wlcg.metricDescription org.wlcg.metricOutput org.wlcg.metricEnvironment
org.wlcg.metricDescription_reqattrs=metricName serviceType metricType
org.wlcg.metricDescription_headerattrs=metricName serviceType
org.wlcg.metricDescription_destination=/topic/grid.probe.metricDescription
...

Experimental features

Publishing client tool supports message-level security by enabling encryption and digital signatures.

Signatures

The message can be signed with the use of user proxy certificate by passing commad line argument -s (user proxy certificate should be taken from location indicated by X509_USER_PROXY variable). In case of multiple tuples publishing public part of user proxy certificate should be attached to the first message in sequence to avoid redundant increase of message size. The successive messages should contain only the SHA1 hash of certificate. This behaviour can be changed with command line argument --no-cert-publish (certificate is not attached to any message in sequence). The signed message is built as follows:

• SHA1 hash of message content is computed
• Hash is encrypted with private key from user proxy certificate
• Encrypted hash is appended to message body (Base64 encoded)
• Public part of user proxy certificate (or its SHA1 hash) is appended to message body in Base64 encoded form
• signedBy header is added to message (signedBy: subject of proxy certificate)
• message-length header is added to message to enable extracting signature from message body (message-length: number of bytes in not signed message)

Encryption

Encryption can be enabled by -e option followed by path to public key of messages' consumer. The key should be encoded in PEM format. In case of enabling both encryption and signing, the message is signed at first (as described above) and then encrypted. The encrypted message is built as follows:

• Message content (pure message or message with attached signature, proxy certificates or certificates' hash) is divided into 100 bytes blocks
• Each block is encrypted and translated to Base64 encoded form
• The new message consists of Base64 encoded, encrypted blocks
• encryptedFor header is added to message indicating encryption

-- PiotrNyczyk - 13 Aug 2007