org.altlinux.jabbix
Class JabbixJSONProtocol

java.lang.Object
  extended by org.altlinux.jabbix.JabbixJSONProtocol

public class JabbixJSONProtocol
extends Object

Constants and functions for the Zabbix agent JSON based protocol.

Author:
Paul Wolneykien

Field Summary
static String ZBX_PROTO_TAG_AVAILABLE
           
static String ZBX_PROTO_TAG_CLOCK
          Defines the time stamp of an entry.
static String ZBX_PROTO_TAG_DATA
          The entry key of an array of metric entries.
static String ZBX_PROTO_TAG_DCHECK
           
static String ZBX_PROTO_TAG_DELAY
          Defines the update period of an active metric defined by the corresponding entry.
static String ZBX_PROTO_TAG_DRULE
           
static String ZBX_PROTO_TAG_ERROR
           
static String ZBX_PROTO_TAG_HOST
          Defines the name of the local host of the agent expected by the server.
static String ZBX_PROTO_TAG_HOSTID
           
static String ZBX_PROTO_TAG_INFO
          Defines a comment for a data processing operation has been done by the server or an error message.
static String ZBX_PROTO_TAG_IP
           
static String ZBX_PROTO_TAG_IPMI_AVAILABLE
           
static String ZBX_PROTO_TAG_IPMI_ERROR
           
static String ZBX_PROTO_TAG_KEY
          Defines the name of an entry.
static String ZBX_PROTO_TAG_KEY_ORIG
           
static String ZBX_PROTO_TAG_LOGEVENTID
           
static String ZBX_PROTO_TAG_LOGLASTSIZE
           
static String ZBX_PROTO_TAG_LOGSEVERITY
           
static String ZBX_PROTO_TAG_LOGSOURCE
           
static String ZBX_PROTO_TAG_LOGTIMESTAMP
           
static String ZBX_PROTO_TAG_MTIME
           
static String ZBX_PROTO_TAG_NODEID
           
static String ZBX_PROTO_TAG_PORT
           
static String ZBX_PROTO_TAG_PROXY
           
static String ZBX_PROTO_TAG_REGEXP
           
static String ZBX_PROTO_TAG_REQUEST
          States the message to be a request to a Zabbix server.
static String ZBX_PROTO_TAG_RESPONSE
          States the message to be a response from a Zabbix server.
static String ZBX_PROTO_TAG_SCRIPTID
           
static String ZBX_PROTO_TAG_SNMP_AVAILABLE
           
static String ZBX_PROTO_TAG_SNMP_ERROR
           
static String ZBX_PROTO_TAG_STATUS
           
static String ZBX_PROTO_TAG_TYPE
           
static String ZBX_PROTO_TAG_VALUE
          Defines the value an entry.
static String ZBX_PROTO_VALUE_AGENT_DATA
          States that the agent sends the list of fresh metric values corresponding to the previously requested set of active checks (see ActiveAgent).
static String ZBX_PROTO_VALUE_AUTO_REGISTRATION_DATA
           
static String ZBX_PROTO_VALUE_DISCOVERY_DATA
           
static String ZBX_PROTO_VALUE_FAILED
          States that the server failed to perform the previously requested operation.
static String ZBX_PROTO_VALUE_GET_ACTIVE_CHECKS
          States that the agent requests the list of active checks, the set of metrics (JabbixActiveMetric) the server is interested in.
static String ZBX_PROTO_VALUE_HISTORY_DATA
           
static String ZBX_PROTO_VALUE_HOST_AVAILABILITY
           
static String ZBX_PROTO_VALUE_PROXY_CONFIG
           
static String ZBX_PROTO_VALUE_PROXY_HEARTBEAT
           
static String ZBX_PROTO_VALUE_SENDER_DATA
           
static String ZBX_PROTO_VALUE_SUCCESS
          States that the server has performed the previously requested operation successfully.
 
Constructor Summary
JabbixJSONProtocol()
           
 
Method Summary
static Collection<JabbixActiveMetric<?>> receiveActiveCheckList(JabbixReader reader)
          Reads and returns an active check list.
static String receiveMetricListResponse(JabbixReader reader)
          Receives the server response for the sent metric data.
static void requestActiveCheckList(JabbixWriter writer, String hostName)
          Requests a set of metrics for "active" monitoring.
static void sendMetricList(JabbixWriter writer, String hostName, Collection<? extends JabbixMetric<?>> metrics)
          Sends the set of metric values to a Zabbix server.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ZBX_PROTO_TAG_CLOCK

public static String ZBX_PROTO_TAG_CLOCK
Defines the time stamp of an entry.

See Also:
sendMetricList(JabbixWriter, String, Collection), ZBX_PROTO_TAG_KEY

ZBX_PROTO_TAG_DATA

public static String ZBX_PROTO_TAG_DATA
The entry key of an array of metric entries.

See Also:
receiveActiveCheckList(JabbixReader), sendMetricList(JabbixWriter, String, Collection)

ZBX_PROTO_TAG_REGEXP

public static String ZBX_PROTO_TAG_REGEXP

ZBX_PROTO_TAG_DELAY

public static String ZBX_PROTO_TAG_DELAY
Defines the update period of an active metric defined by the corresponding entry.

See Also:
receiveActiveCheckList(JabbixReader), ZBX_PROTO_TAG_KEY, JabbixActiveMetric

ZBX_PROTO_TAG_DRULE

public static String ZBX_PROTO_TAG_DRULE

ZBX_PROTO_TAG_DCHECK

public static String ZBX_PROTO_TAG_DCHECK

ZBX_PROTO_TAG_HOST

public static String ZBX_PROTO_TAG_HOST
Defines the name of the local host of the agent expected by the server.

See Also:
requestActiveCheckList(JabbixWriter, String), sendMetricList(JabbixWriter, String, Collection)

ZBX_PROTO_TAG_INFO

public static String ZBX_PROTO_TAG_INFO
Defines a comment for a data processing operation has been done by the server or an error message.

See Also:
receiveMetricListResponse(JabbixReader), requestActiveCheckList(JabbixWriter, String)

ZBX_PROTO_TAG_IP

public static String ZBX_PROTO_TAG_IP

ZBX_PROTO_TAG_KEY

public static String ZBX_PROTO_TAG_KEY
Defines the name of an entry. If the entry represents a metric the name of the latter is marked with this tag.

See Also:
receiveActiveCheckList(JabbixReader), sendMetricList(JabbixWriter, String, Collection), ZBX_PROTO_TAG_DELAY, ZBX_PROTO_TAG_CLOCK, ZBX_PROTO_TAG_VALUE, JabbixActiveMetric

ZBX_PROTO_TAG_KEY_ORIG

public static String ZBX_PROTO_TAG_KEY_ORIG

ZBX_PROTO_TAG_LOGLASTSIZE

public static String ZBX_PROTO_TAG_LOGLASTSIZE

ZBX_PROTO_TAG_MTIME

public static String ZBX_PROTO_TAG_MTIME

ZBX_PROTO_TAG_LOGTIMESTAMP

public static String ZBX_PROTO_TAG_LOGTIMESTAMP

ZBX_PROTO_TAG_LOGSOURCE

public static String ZBX_PROTO_TAG_LOGSOURCE

ZBX_PROTO_TAG_LOGSEVERITY

public static String ZBX_PROTO_TAG_LOGSEVERITY

ZBX_PROTO_TAG_LOGEVENTID

public static String ZBX_PROTO_TAG_LOGEVENTID

ZBX_PROTO_TAG_PORT

public static String ZBX_PROTO_TAG_PORT

ZBX_PROTO_TAG_PROXY

public static String ZBX_PROTO_TAG_PROXY

ZBX_PROTO_TAG_REQUEST

public static String ZBX_PROTO_TAG_REQUEST
States the message to be a request to a Zabbix server. The corresponding value should state the sort of the request being made.

See Also:
ZBX_PROTO_TAG_RESPONSE, requestActiveCheckList(JabbixWriter, String), sendMetricList(JabbixWriter, String, Collection), ZBX_PROTO_VALUE_GET_ACTIVE_CHECKS, ZBX_PROTO_VALUE_AGENT_DATA

ZBX_PROTO_TAG_RESPONSE

public static String ZBX_PROTO_TAG_RESPONSE
States the message to be a response from a Zabbix server. The corresponding value should state the status of the response, i.e. the status of the requested operation.

See Also:
ZBX_PROTO_TAG_REQUEST, receiveActiveCheckList(JabbixReader), receiveMetricListResponse(JabbixReader), ZBX_PROTO_VALUE_SUCCESS, ZBX_PROTO_VALUE_FAILED

ZBX_PROTO_TAG_STATUS

public static String ZBX_PROTO_TAG_STATUS

ZBX_PROTO_TAG_TYPE

public static String ZBX_PROTO_TAG_TYPE

ZBX_PROTO_TAG_VALUE

public static String ZBX_PROTO_TAG_VALUE
Defines the value an entry. If the entry represents a metric the value of the latter is marked with this tag.

See Also:
sendMetricList(JabbixWriter, String, Collection), ZBX_PROTO_TAG_KEY, JabbixActiveMetric

ZBX_PROTO_TAG_SCRIPTID

public static String ZBX_PROTO_TAG_SCRIPTID

ZBX_PROTO_TAG_HOSTID

public static String ZBX_PROTO_TAG_HOSTID

ZBX_PROTO_TAG_NODEID

public static String ZBX_PROTO_TAG_NODEID

ZBX_PROTO_TAG_AVAILABLE

public static String ZBX_PROTO_TAG_AVAILABLE

ZBX_PROTO_TAG_SNMP_AVAILABLE

public static String ZBX_PROTO_TAG_SNMP_AVAILABLE

ZBX_PROTO_TAG_IPMI_AVAILABLE

public static String ZBX_PROTO_TAG_IPMI_AVAILABLE

ZBX_PROTO_TAG_ERROR

public static String ZBX_PROTO_TAG_ERROR

ZBX_PROTO_TAG_SNMP_ERROR

public static String ZBX_PROTO_TAG_SNMP_ERROR

ZBX_PROTO_TAG_IPMI_ERROR

public static String ZBX_PROTO_TAG_IPMI_ERROR

ZBX_PROTO_VALUE_FAILED

public static String ZBX_PROTO_VALUE_FAILED
States that the server failed to perform the previously requested operation.

See Also:
ZBX_PROTO_TAG_RESPONSE, receiveActiveCheckList(JabbixReader), receiveMetricListResponse(JabbixReader)

ZBX_PROTO_VALUE_SUCCESS

public static String ZBX_PROTO_VALUE_SUCCESS
States that the server has performed the previously requested operation successfully.

See Also:
ZBX_PROTO_TAG_RESPONSE, receiveActiveCheckList(JabbixReader), receiveMetricListResponse(JabbixReader)

ZBX_PROTO_VALUE_GET_ACTIVE_CHECKS

public static String ZBX_PROTO_VALUE_GET_ACTIVE_CHECKS
States that the agent requests the list of active checks, the set of metrics (JabbixActiveMetric) the server is interested in.

See Also:
ZBX_PROTO_TAG_REQUEST, requestActiveCheckList(JabbixWriter, String)

ZBX_PROTO_VALUE_PROXY_CONFIG

public static String ZBX_PROTO_VALUE_PROXY_CONFIG

ZBX_PROTO_VALUE_PROXY_HEARTBEAT

public static String ZBX_PROTO_VALUE_PROXY_HEARTBEAT

ZBX_PROTO_VALUE_DISCOVERY_DATA

public static String ZBX_PROTO_VALUE_DISCOVERY_DATA

ZBX_PROTO_VALUE_HOST_AVAILABILITY

public static String ZBX_PROTO_VALUE_HOST_AVAILABILITY

ZBX_PROTO_VALUE_HISTORY_DATA

public static String ZBX_PROTO_VALUE_HISTORY_DATA

ZBX_PROTO_VALUE_AUTO_REGISTRATION_DATA

public static String ZBX_PROTO_VALUE_AUTO_REGISTRATION_DATA

ZBX_PROTO_VALUE_SENDER_DATA

public static String ZBX_PROTO_VALUE_SENDER_DATA

ZBX_PROTO_VALUE_AGENT_DATA

public static String ZBX_PROTO_VALUE_AGENT_DATA
States that the agent sends the list of fresh metric values corresponding to the previously requested set of active checks (see ActiveAgent).

See Also:
ZBX_PROTO_TAG_REQUEST, sendMetricList(JabbixWriter, String, Collection)
Constructor Detail

JabbixJSONProtocol

public JabbixJSONProtocol()
Method Detail

requestActiveCheckList

public static void requestActiveCheckList(JabbixWriter writer,
                                          String hostName)
                                   throws IOException
Requests a set of metrics for "active" monitoring. The requested set can be received with the use of the receiveActiveCheckList(JabbixReader) method.

The following JSON message is composed and sent to the server:

 {"request": "active checks",
  "host": "<host name>"}
 
The host name (host) parameter is the name of the local host expected by the server (see ZabbixClient.getHostName()).

Parameters:
writer - a writer connected to a socket
hostName - the name of the local host
Throws:
IOException - if there was an I/O exception during the request dispatch
See Also:
ZBX_PROTO_TAG_REQUEST, ZBX_PROTO_VALUE_GET_ACTIVE_CHECKS, ZBX_PROTO_TAG_HOST

receiveActiveCheckList

public static Collection<JabbixActiveMetric<?>> receiveActiveCheckList(JabbixReader reader)
                                                                throws IOException,
                                                                       JabbixException,
                                                                       JabbixProtocolException
Reads and returns an active check list. Used to read the previously requested information on metrics for "active" monitoring.

The JSON message of the following form (structure) is expected:

 {
     "response": "success",
     "data":
     [
         { "key": "<metric key>",
           "delay":"<update period>" },
         { "key": "<metric key>",
           "delay":"<update period>" },

         ...

     ]
  }
 

The meric key (key) parameter of each entry is the name of the metric (see JabbixActiveMetric) which value the server expects to receive periodically.

The period of a metric value update is defined by the corresponding update period (delay) parameter.

If the server is unable to send the requested active check list the server sends the message with an unsuccessful status and an optional comment (see receiveMetricListResponse(JabbixReader)).

Parameters:
reader - a reader connected to a socket
Returns:
a set of JabbixActiveMetric objects representing the active check list
Throws:
IOException - if there was an I/O exception during the response reception
JabbixException - if the server sent an unsuccessful status
JabbixProtocolException - if the protocol was violated (i.e. an unexpected value was received)
See Also:
requestActiveCheckList(JabbixWriter,String), ZBX_PROTO_TAG_RESPONSE, ZBX_PROTO_VALUE_SUCCESS, ZBX_PROTO_TAG_DATA, ZBX_PROTO_TAG_KEY, ZBX_PROTO_TAG_DELAY, ZBX_PROTO_VALUE_FAILED

sendMetricList

public static void sendMetricList(JabbixWriter writer,
                                  String hostName,
                                  Collection<? extends JabbixMetric<?>> metrics)
                           throws IOException
Sends the set of metric values to a Zabbix server. The server replies with the status message (see receiveMetricListResponse(JabbixReader)).

The following JSON message is composed and sent to the server:

 {
     "request": "agent data",
     "data":
     [
         { "host": "<host name>",
           "key": "<metric key>",
           "value": "<metric value>",
           "clock": <metric time stamp>" },
         { "host": "<host name>",
           "key": "<metric key>",
           "value": "<metric value>",
           "clock": <metric time stamp>" },

         ...

     ]
     "clock": <message time stamp>
 }
 
The host name (host) parameter is the name of the local host expected by the server (see ZabbixClient.getHostName()).

The meric key (key) parameter of each entry is the name of the metric (see JabbixActiveMetric) which value the server expects to receive periodically.

The metric value (value) parameter is the value of the metric represented as a textual string. Because of the metric value has not to be sent just after its update, the special metric time stamp (clock) entry parameter is used to explicitly state the update time (see JabbixActiveMetric.getUpdated()).

It also seems to be useful to state the time of the request itself. The message time stamp (clock) top-level parameter is used for that porpose.

Parameters:
writer - a writer connected to a socket
hostName - the name of the local host
metrics - the set of metrics
Throws:
IOException - if there was an I/O exception during the dispatch
See Also:
ZBX_PROTO_TAG_REQUEST, ZBX_PROTO_VALUE_AGENT_DATA, ZBX_PROTO_TAG_HOST, ZBX_PROTO_TAG_KEY, ZBX_PROTO_TAG_VALUE, ZBX_PROTO_TAG_CLOCK, ZBX_PROTO_TAG_DATA

receiveMetricListResponse

public static String receiveMetricListResponse(JabbixReader reader)
                                        throws IOException,
                                               JabbixException,
                                               JabbixProtocolException
Receives the server response for the sent metric data.

The JSON message of the following form (structure) is expected:

 { "response": "<status>",
   "info": "<comment>" }
 
In the successful case the status (response) parameter is stated as success. And the comment (info) parameter contains a human-readable comment on the data processing has been done.

In the case of an error the status can be stated as failed or any other non-successful value. The comment parameter may or may not be present.

Parameters:
reader - a reader connected to a socket
Returns:
the server response message
Throws:
IOException - if there was an I/O exception during the response reception
JabbixException - if the server sent an unsuccessful status
JabbixProtocolException - if the protocol was violated (i.e. an unexpected value was received)
See Also:
ZBX_PROTO_TAG_RESPONSE, ZBX_PROTO_VALUE_SUCCESS, ZBX_PROTO_TAG_INFO, ZBX_PROTO_VALUE_FAILED