Monitoring Protocol

Protocol Elements

The three main protocol data units are commands, command status responses and metric values. Every command has an identifier (e.g. COLLECT or GET) and a sequence number. Responses have a status code, the same sequence number as the original command and an optional result identifier. It is possible to issue multiple commands without waiting for a response for the previous command to arrive. In case of multiple parallel commands the protocol does not guarantee that the order of responses matches the order of the original commands. Responses should be matched to commands by command sequence numbers.

The producer is allowed to send metric values at any time. The only restriction is that if a metric value is being sent as a result of a command, the response for the command must precede the requested data (i.e. when using the GET command to request data, the response for the GET command will be sent before the metric values corresponding to this command).

Apart from metric values containing requested measurements the producer may also send messages describing producer capabilities or containing an authentication response. Authentication response messages are sent by the producer when mutual or multi-step authentication is needed (see below). Producer capabilities are sent to the consumer when a channel is opened or when they change (for example, installing an encryption layer over the channel might change the list of available authentication methods).

A channel is a logical connection between a producer and a consumer defined over a physical network connection. Each channel has a channel identifier which is assigned by, and specific to, the producer. There are two special channel identifiers a consumer can use. One references all channels defined between it and the producer it is talking to, the other references the current channel. When a network connection is opened between a producer and a consumer, the producer automatically defines a channel and makes it the current channel. The consumer can later define new channels and change the current channel.

Commands

The consumer can use the following commands:

AUTH

  • Arguments: authentication method (string), method-specific data (opaque)

  • Response: error code, channel identifier

The AUTH command authenticates the user to the monitoring system. Unless explicitly stated otherwise the consumer must not send any other commands to the producer before a successful authentication; trying to do so will result in an error. Issuing the AUTH command on an already authenticated channel will also result in an error.

The method-specific data contain the credentials needed to verify the identity of the user. For example, they can be a user name and a password for password authentication.

The AUTH command may return the status code MON_STATUS_AUTH_NEEDED to indicate that more authentication steps are needed. In this case exactly one authentication response message will be sent that contains the producer's response to the consumer's challenge. After processing this message the AUTH command should be used again with leaving the authentication method string empty. This procedure should be repeated until the producer either accepts or rejects the authentication. If the authentication was successful an identifier for the current channel will be returned.

COLLECT

  • Arguments: metric name (string), parameter list (Argument list)

  • Response: error code, metric identifier

The COLLECT command instructs the monitoring system to create a metric instance with the given parameters. If this is successful, the response contains the metric identifier of the metric instance. The parameter list is a list of name/value pairs.

STOP

  • Arguments: metric identifier (uint32), channel identifier (uint32)

  • Response: error code

The STOP command tells the monitoring system that no more metric values for this identifier should be sent to the specified channel. Metric values for this identifier that have been queued in the monitoring system for the specified channel will be lost.

If the metric identifier is still subscribed to other channels, both the GET and SUBSCRIBE commands can be used to receive further metric values for this metric id. If there are no other channels where this metric identifier is subscribed, the STOP command will destroy the metric instance and all further references to this metric instance will result in an error.

SUBSCRIBE

  • Arguments: metric identifier (uint32), channel identifier (uint32)

  • Response: error code

The SUBSCRIBE command instructs the monitoring system that all metric values for the given metric identifier should be automatically sent to the specified channel. The same metric identifier can be subscribed to more than one channel by using the SUBSCRIBE command multiple times. If there were metric values queued for the given metric identifier on the current channel they will be copied to the destination channel.

BUFFER

  • Arguments: metric identifier (uint32), channel identifier (uint32)

  • Response: error code

The BUFFER command instructs the monitoring system that all metric values for the given metric identifier should be buffered on the specified channel. It is possible to use the SUBSCRIBE and BUFFER commands for the same metric identifier on different channels.

GET

  • Arguments: metric identifier (uint32), channel identifier (uint32)

  • Response: error code

The GET command performs the following tasks:

  • For event-like metrics, if there are metric values queued for the given metric identifier on the given channel, the monitoring system will send them to the consumer.

  • For continuously measurable metrics, a new measurement is requested from the appropriate sensor. When the measurement is ready, the measured metric value will be sent to the consumer on the given channel. The monitoring system makes no guarantee when (if ever) this metric value will be sent.

DEF_CHANNEL

  • Arguments: Destination URL (string), parameter list (Argument list)

  • Response: error code, channel identifier

The DEF_CHANNEL command defines a producer initiated channel that the monitoring system should open to the specified external location.

SET_CHANNEL

  • Arguments: Channel identifier (uint32)

  • Response: error code

The SET_CHANNEL command changes the current channel to the one identified by the given channel identifier while keeping the network connection. If the destination channel had an open network connection it will be closed.

DEL_CHANNEL

  • Arguments: Channel identifier (uint32)

  • Response: error code

The DEL_CHANNEL command destroys a channel. Metric instances associated with the destination channel but not associated with any other channels are destroyed. All data queued on the channel are discarded and the network connection (if open) is closed. The value of 0 for the channel identifier means the current channel.

COMMIT

  • Arguments: Transaction identifier (uint64)

  • Response: error code

The COMMIT command informs the producer that the consumer has successfully processed the metric value belonging to the given transaction identifier.

EXECUTE

  • Arguments: control name (string), parameter list (Argument list)

  • Response: error code, result identifier

The EXECUTE command executes the named control with the given arguments. The command response contains an identifier for the control's result. The result has the same format as a metric value and the identifier returned by the command response.

QUERY

  • Arguments: metric name (string), parameter list (Argument list)

  • Response: error code, metric identifier

The QUERY command is an optimization for fast information retrieval. It is equivalent to a COLLECT - GET - STOP command sequence. Due to its nature it can only be used with continuously measurable metrics. It is guaranteed that at most one metric value will be sent by the producer as the result of the command. However it is not guaranteed when (if ever) that metric value will be sent since this depends on the sensor.

WRAP

  • Arguments: I/O layer identifier (string)

  • Response: error code, producer capabilities (optional)

The WRAP command installs an I/O transformation layer on the current channel. This command can be used to turn on transparent compression or to activate data encryption.

Unlike the other commands WRAP must be used synchronously. That is, the consumer must wait for the completion of the command before issuing any other commands to the producer. If the command succeeds, any subsequent data sent or received on the channel should go through the transformation (compression, encryption, etc.) defined by this I/O layer.

The WRAP command unlike other commands, may be used on an unauthenticated channel if the producer advertised any available transformations in the producer capability list. Doing so might change the producer capabilities available to the consumer (e.g., if an encryption layer is installed, authentication methods using clear text secrets might become available). If this is the case, the command result identifier in the command status response will contain the MON_MID_PRODUCER_CAPS value and the new set of producer capabilities will be sent to the consumer.

If the transformation layer requires any handshaking or other internal communication between the peers it should happen below the level of the monitoring protocol and is not described here.