4 Zabbix agent 2 plugin protocol

4 Zabbix agent 2 plugin protocol

Zabbix agent 2 protocol is based on code, size and data model.

Code

Type	Size	Comments
Byte	4	Payload type, currently only JSON is supported.

Size

Type	Size	Comments
Byte	4	Size of the current payload in bytes.

Payload data

Type	Size	Comments
Byte	Defined by the Size field	JSON formatted data.

Payload data definition

Common data

These parameters are present in all requests/responses:

Name	Type	Comments
id	uint32	For requests - the incrementing identifier used to link requests with responses. Unique within a request direction (i.e. from agent to plugin or from plugin to agent). For responses - ID of the corresponding request.
type	uint32	The request type.

Log request

A request sent by a plugin to write a log message into the agent log file.

direction	plugin → agent
response	no

Parameters specific to log requests:

Name	Type	Comments
severity	uint32	The message severity (log level).
message	string	The message to log.

Example:

{"id":0,"type":1,"severity":3,"message":"message"}

Register request

A request sent by the agent during the agent startup phase to obtain provided metrics to register a plugin.

direction	agent → plugin
response	yes

Parameters specific to register requests:

Name	Type	Comments
version	string	The protocol version <major>.<minor>

Example:

{"id":1,"type":2,"version":"1.0"}

Register response

Plugin’s response to the register request.

direction	plugin → agent
response	n/a

Parameters specific to register responses:

Name	Type	Comments
name	string	The plugin name.
metrics	array of strings (optional)	The metrics with descriptions as used in the plugin. Returns RegisterMetrics(). Absent if error is returned.
interfaces	uint32 (optional)	The bit mask of plugin’s supported interfaces. Absent if error is returned.
error	string (optional)	An error message returned if a plugin cannot be started. Absent, if metrics are returned.

Examples:

{"id":2,"type":3,"metrics":["external.test", "External exporter Test."], "interfaces": 4}

{"id":2,"type":3,"error":"error message"}

Start request

A request to execute the Start function of the Runner interface.

direction	agent → plugin
response	no

The request doesn’t have specific parameters, it only contains common data parameters.

Example:

{"id":3,"type":4}

Terminate request

A request sent by the agent to shutdown a plugin.

direction	agent → plugin
response	no

The request doesn’t have specific parameters, it only contains common data parameters.

Example:

{"id":3,"type":5}

Export request

A request to execute the Export function of the Exporter interface.

direction	agent → plugin
response	no

Parameters specific to export requests:

Name	Type	Comments
key	string	The plugin key.
parameters	array of strings (optional)	The parameters for Export function.

Example:

{"id":4,"type":6,"key":"test.key","parameters":["foo","bar"]}

Export response

Response from the Export function of the Exporter interface.

direction	plugin → agent
response	n/a

Parameters specific to export responses:

Name	Type	Comments
value	string (optional)	Response value from the Export function. Absent, if error is returned.
error	string (optional)	Error message if the Export function has not been executed successfully. Absent, if value is returned.

Examples:

{"id":5,"type":7,"value":"response"}

{"id":5,"type":7,"error":"error message"}

Configure request

A request to execute the Configure function of the Configurator interface.

direction	agent → plugin
response	n/a

Parameters specific to Configure requests:

Name	Type	Comments
global_options	JSON object	JSON object containing global agent configuration options.
private_options	JSON object (optional)	JSON object containing private plugin configuration options, if provided.

Example:

{"id":6,"type":8,"global_options":{...},"private_options":{...}}

Validate request

A request to execute Validate function of the Configurator interface.

direction	agent → plugin
response	yes

Parameters specific to Validate requests:

Name	Type	Comments
private_options	JSON object (optional)	JSON object containing private plugin configuration options, if provided.

Example:

{"id":7,"type":9,"private_options":{...}}

Validate response

Response from Validate function of Configurator interface.

direction	plugin → agent
response	n/a

Parameters specific to Validate responses:

Name	Type	Comments
error	string (optional)	An error message returned if the Validate function is not executed successfully. Absent if executed successfully.

Example:

{"id":8,"type":10}

{"id":8,"type":10,"error":"error message"}