Documentation
Table of Contents
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:
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:
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:
or
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:
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:
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:
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:
or
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:
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:
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:
or