Protocol Definitions

Protocol Definitions — Constants and data structures used by both the consumer and the producer

Synopsis


#include <monitor/monitor.h>


#define     MON_PROTO_MINOR
#define     MON_PROTO_MAJOR
enum        mon_cmd;
#define     MON_CMD_MAX_CMD
#define     MON_METRIC_ID_MASK
#define     MON_METRIC_ID_SPECIAL
#define     MON_CHANNEL_CURRENT
#define     MON_METRIC_ID_MIN
#define     MON_METRIC_ID_MAX
enum        mon_special_mid;
enum        mon_cmd_status;
enum        mon_format;
            mon_msg_cmd_response;
            mon_msg_producer_caps;
            mon_msg_data;
mon_format  mon_msg_format                  (uint32_t metric_id);
const char* mon_cmd_tostring                (mon_cmd cmd);
mon_cmd_status mon_cmd_err2status           (int err);
int         mon_cmd_status2err              (mon_cmd_status status);

Description

The <monitor/protocol.h> header contains constants that directly affect the wire protocol as well as data types used by both the consumer and producer APIs.

Details

MON_PROTO_MINOR

#define MON_PROTO_MINOR		1

Minor version of the implemented protocol

MON_PROTO_MAJOR

#define MON_PROTO_MAJOR		1

Major version of the implemented protocol

enum mon_cmd

typedef enum {
	MON_CMD_NOP,
	MON_CMD_COLLECT,
	MON_CMD_STOP,
	MON_CMD_SUBSCRIBE,
	MON_CMD_BUFFER,
	MON_CMD_GET,
	MON_CMD_AUTH,
	MON_CMD_DEF_CHANNEL,
	MON_CMD_SET_CHANNEL,
	MON_CMD_DEL_CHANNEL,
	MON_CMD_COMMIT,
	MON_CMD_EXECUTE,
	MON_CMD_QUERY,
	MON_CMD_WRAP
} mon_cmd;

The list of commands defined for the monitoring protocol.

`MON_CMD_NOP`	No-operation. Can be used to implement keepalive.
`MON_CMD_COLLECT`	Create a metric instance.
`MON_CMD_STOP`	Stop receiving data from a metric instance.
`MON_CMD_SUBSCRIBE`	Subscribe a metric instance to a channel.
`MON_CMD_BUFFER`	Buffer measurements from a metric instance on a channel.
`MON_CMD_GET`	Retrieve buffered data or perform a new measurement.
`MON_CMD_AUTH`	Perform authentication.
`MON_CMD_DEF_CHANNEL`	Define a new producer-initiated channel.
`MON_CMD_SET_CHANNEL`	Replace the current logical channel.
`MON_CMD_DEL_CHANNEL`	Close and delete a channel.
`MON_CMD_COMMIT`	Acknowledge a received metric value.
`MON_CMD_EXECUTE`	Execute a control in the producer.
`MON_CMD_QUERY`	Shorthand for COLLECT - GET - STOP.
`MON_CMD_WRAP`	Negotiate a new transport layer (compression, encryption etc.).

MON_CMD_MAX_CMD

#define MON_CMD_MAX_CMD		MON_CMD_WRAP

The value of the largest command code.

MON_METRIC_ID_MASK

#define MON_METRIC_ID_MASK	0xffffff

Bitmask for separating metric identifier values from other flags.

MON_METRIC_ID_SPECIAL

#define MON_METRIC_ID_SPECIAL	128

The first special metric that have the normal metric value format.

MON_CHANNEL_CURRENT

#define MON_CHANNEL_CURRENT	0

The identifier of the current channel.

MON_METRIC_ID_MIN

#define MON_METRIC_ID_MIN	256

This macro defines the smallest value the producer is allowed to allocate to normal metric IDs.

MON_METRIC_ID_MAX

#define MON_METRIC_ID_MAX	((1 << 24) - 1)

This macro defines the largest value the producer is allowed to allocate to normal metric IDs.

enum mon_special_mid

typedef enum {
	MON_MID_CMD_RESPONSE,
	MON_MID_PRODUCER_CAPS,
	MON_MID_AUTH_RESPONSE,
	MON_MID_KILLED = 128,
	MON_MID_DROPPED
} mon_special_mid;

List of special metric identifiers. These identifiers are used for system messages.

`MON_MID_CMD_RESPONSE`	The message is a command response.
`MON_MID_PRODUCER_CAPS`	The message is the list of producer capabilities.
`MON_MID_AUTH_RESPONSE`	The message is an authentication response.
`MON_MID_KILLED`	Message telling that a metric identifier is no longer valid.
`MON_MID_DROPPED`	Message telling that the producer had to drop some messages due to the queue size exceeding resource limits.

enum mon_cmd_status

typedef enum {
	MON_STATUS_OK,
	MON_STATUS_GENERIC_ERR,
	MON_STATUS_UNKNOWN_CMD,
	MON_STATUS_UNKNOWN_METRIC,
	MON_STATUS_UNKNOWN_CHANNEL,
	MON_STATUS_BADPARAM,
	MON_STATUS_PARAM_TYPE,
	MON_STATUS_PARAM_MULTIPLE,
	MON_STATUS_PARAM_UNKNOWN,
	MON_STATUS_PARAM_MISSING,
	MON_STATUS_AUTH_NEEDED,
	MON_STATUS_AUTH_ERR,
	MON_STATUS_ACCESS_DENIED,
	MON_STATUS_RES_LIMIT,
	MON_STATUS_METRIC_KILLED,
	MON_STATUS_UNKNOWN_CONTROL,
	MON_STATUS_ABORTED
} mon_cmd_status;

Status codes that the producer can return for a command.

`MON_STATUS_OK`	No error.
`MON_STATUS_GENERIC_ERR`	Generic error in the producer.
`MON_STATUS_UNKNOWN_CMD`	Unknown command.
`MON_STATUS_UNKNOWN_METRIC`	Unknown metric.
`MON_STATUS_UNKNOWN_CHANNEL`	Unknown channel.
`MON_STATUS_BADPARAM`	Bad metric parameters.
`MON_STATUS_PARAM_TYPE`	Parameter type mismatch.
`MON_STATUS_PARAM_MULTIPLE`	Non-multivalued parameter specified multiple times.
`MON_STATUS_PARAM_UNKNOWN`	Unknown parameter.
`MON_STATUS_PARAM_MISSING`	Required parameter is missing.
`MON_STATUS_AUTH_NEEDED`	Authentication is needed.
`MON_STATUS_AUTH_ERR`	Authentication error.
`MON_STATUS_ACCESS_DENIED`	Access denied by the producer.
`MON_STATUS_RES_LIMIT`	Resource limits exceeded.
`MON_STATUS_METRIC_KILLED`	The metric instance was killed.
`MON_STATUS_UNKNOWN_CONTROL`	Unknown control.
`MON_STATUS_ABORTED`	The operation was aborted inside the producer.

enum mon_format

typedef enum {
	MON_FORMAT_UNKNOWN = -1,
	MON_FORMAT_CMD_RESPONSE,
	MON_FORMAT_PRODUCER_CAPS,
	MON_FORMAT_DATA,
	MON_FORMAT_METRIC
} mon_format;

Possible formats of messages sent by the producer.

`MON_FORMAT_UNKNOWN`	The message format is unknown.
`MON_FORMAT_CMD_RESPONSE`	The message is a command response (mon_msg_cmd_response).
`MON_FORMAT_PRODUCER_CAPS`	The message is a set of producer capabilities (mon_msg_producer_caps).
`MON_FORMAT_DATA`	The message contains generic binary data (mon_msg_data).
`MON_FORMAT_METRIC`	The message contains a metric value (monp_metric_value, prod_metric_value).

mon_msg_cmd_response

typedef struct {
	uint32_t		cmd_seq;
	mon_cmd_status		status;
	uint32_t		param;
} mon_msg_cmd_response;

The mon_msg_cmd_response struct represents a response for a previous command.

uint32_t `cmd_seq`;	the command's sequence number.
mon_cmd_status `status`;	the command's result status.
uint32_t `param`;	optional paramerer (metric or channel id).

mon_msg_producer_caps

typedef struct {
	unsigned int		ver_major;
	unsigned int		ver_minor;
	mon_arg_list		*caps;
} mon_msg_producer_caps;

The mon_msg_producer_caps structure contains the list of producer capabilities that are returned when a connection is made.

unsigned int `ver_major`;	the major version of the protocol.
unsigned int `ver_minor`;	the minor version of the protocol.
mon_arg_list *`caps`;	producer capability list.

mon_msg_data

typedef struct {
	char			*data;
	uint32_t		len;
} mon_msg_data;

The mon_msg_data structure contains generic binary data.

char *`data`;	opaque data.
uint32_t `len`;	length of `data`.

mon_msg_format ()

mon_format  mon_msg_format                  (uint32_t metric_id);

Determine the format of a message.

`metric_id` :	the metric ID of the message.
Returns :	the message format.

mon_cmd_tostring ()

const char* mon_cmd_tostring                (mon_cmd cmd);

Converts a protocol command id to a string.

`cmd` :	a mon_cmd.
Returns :	the stringified command.

mon_cmd_err2status ()

mon_cmd_status mon_cmd_err2status           (int err);

Converts an internal error code to a protocol status code.

`err` :	an error code.
Returns :	a protocol status code.

mon_cmd_status2err ()

int         mon_cmd_status2err              (mon_cmd_status status);

Converts a protocol status code to an internal error code.

`status` :	a protocol status code.
Returns :	an error code.