Table of Contents
25 Scatter plot
Description
These parameters and the possible property values for the respective dashboard widget field objects allow to configure the Scatter plot widget in dashboard.create and dashboard.update methods.
Widget fields properties are not validated during the creation or update of a dashboard. This allows users to modify built-in widgets and create custom widgets, but also introduces the risk of creating or updating widgets incorrectly. To ensure the successful creation or update of the Scatter plot widget, please refer to the parameter behavior outlined in the tables below.
Parameters
The following parameters are supported for the Scatter plot widget.
| Parameter | type | name | value |
|---|---|---|---|
| Refresh interval | 0 | rf_rate | 0 - No refresh; 10 - 10 seconds; 30 - 30 seconds; 60 - (default) 1 minute; 120 - 2 minutes; 600 - 10 minutes; 900 - 15 minutes. |
| Reference | 1 | reference | Any string value consisting of 5 characters (e.g., ABCDE or JBPNL). This value must be unique within the dashboard to which the widget belongs.Parameter behavior: - required |
Data set
The following parameters are supported for configuring a Data set.
The first number in the property name (e.g., ds.0.hosts.0, ds.0.items.0) represents the particular data set, while the second number, if present, represents the configured host or item.
| Parameter | type | name | value | |
|---|---|---|---|---|
| Data set type | 0 | ds.0.dataset_type | 0 - Item list; 1 - (default) Item patterns. |
|
| Data set: Item list | ||||
| Color | 1 | ds.0.color.0 | Hexadecimal color code (e.g., FF0000).Parameter behavior: - required if Data set type is set to "Item list" |
|
| X-Axis | 4 | ds.0.x_axis_itemids.0 | Item ID. When configuring the widget on a template dashboard, only items configured on the template should be set. Note: To configure multiple items, create a dashboard widget field object for each item with an incremented number in the property name. Parameter behavior: - required if Data set type is set to "Item list" and X-axis (Widget) is not set |
|
| X-Axis (Widget) | 1 | ds.0.x_axis_itemids.0._reference | Instead of Item ID:ABCDE._itemid - set a compatible widget (with its Reference parameter set to "ABCDE") as the data source for items.Note: To configure multiple widgets, create a dashboard widget field object for each widget with an incremented number in the property name. Parameter behavior: - required if Data set type is set to "Item list" and X-Axis is not set |
|
| Y-Axis | 4 | ds.0.y_axis_itemids.0 | Item ID. When configuring the widget on a template dashboard, only items configured on the template should be set. Note: To configure multiple items, create a dashboard widget field object for each item with an incremented number in the property name. Parameter behavior: - required if Data set type is set to "Item list" and Y-axis (Widget) is not set |
|
| Y-Axis (Widget) | 1 | ds.0.y_axis_itemids.0._reference | Instead of Item ID:ABCDE._itemid - set a compatible widget (with its Reference parameter set to "ABCDE") as the data source for items.Note: To configure multiple widgets, create a dashboard widget field object for each widget with an incremented number in the property name. Parameter behavior: - required if Data set type is set to "Item list" and Y-Axis is not set |
|
| Override host | 1 | ds.0.override_hostid._reference | ABCDE._hostid- set a compatible widget (with its "Reference" parameter set to "ABCDE") as the data source for hosts;DASHBOARD._hostid - set the dashboard host selector as the data source for hosts.This parameter is not supported if configuring the widget on a template dashboard. |
|
| Data set: Item patterns | ||||
| Color | 1 | ds.0.color | Hexadecimal color code (e.g., FF0000).Parameter behavior: - supported if Data set type is set to "Item patterns" and Color palette is not set |
|
| Color palette | 0 | ds.0.color_palette | Color palette index. Possible values range: 0-11. Default: 0. Parameter behavior: - supported if Data set type is set to "Item patterns" and Color is not set |
|
| Host patterns | 1 | ds.0.hosts.0 | Host name or pattern (e.g., "Zabbix*"). Parameter behavior: - required if Data set type is set to "Item patterns" This parameter is not supported if configuring the widget on a template dashboard. |
|
| X-Axis item patterns | 1 | ds.0.x_axis_items.0 | Item name or pattern (e.g., "*: Number of processed *values per second"). When configuring the widget on a template dashboard, only the patterns for items configured on the template should be set. Parameter behavior: - required if Data set type is set to "Item patterns" |
|
| Y-Axis item patterns | 1 | ds.0.y_axis_items.0 | Item name or pattern (e.g., "*: Number of processed *values per second"). When configuring the widget on a template dashboard, only the patterns for items configured on the template should be set. Parameter behavior: - required if Data set type is set to "Item patterns" |
|
| Host groups | 2 | groupids.0 | Host group ID. Note: To configure multiple host groups, create a dashboard widget field object for each host group with an incremented number in the property name. This parameter is not supported if configuring the widget on a template dashboard. |
|
| Host groups (Widget) | 1 | groupids._reference | Instead of Host group ID:ABCDE._hostgroupids - set a compatible widget (with its Reference parameter set to "ABCDE") as the data source for host groups.This parameter is not supported if configuring the widget on a template dashboard. |
|
| Override host | 1 | ds.0.override_hostid._reference | ABCDE._hostid- set a compatible widget (with its "Reference" parameter set to "ABCDE") as the data source for hosts;DASHBOARD._hostid - set the dashboard host selector as the data source for hosts.This parameter is not supported if configuring the widget on a template dashboard. |
|
| Host tags | ||||
| Evaluation type | 0 | evaltype_host | 0 - (default) And/Or; 2 - Or. This parameter is not supported if configuring the widget on a template dashboard. |
|
| Tag name | 1 | host_tags.0.tag | Any string value. Note: The number in the property name references tag order in the tag evaluation list. Parameter behavior: - required if configuring Host tags This parameter is not supported if configuring the widget on a template dashboard. |
|
| Operator | 0 | host_tags.0.operator | 0 - Contains; 1 - Equals; 2 - Does not contain; 3 - Does not equal; 4 - Exists; 5 - Does not exist. Note: The number in the property name references tag order in the tag evaluation list. Parameter behavior: - required if configuring Host tags This parameter is not supported if configuring the widget on a template dashboard. |
|
| Tag value | 1 | host_tags.0.value | Any string value. Note: The number in the property name references tag order in the tag evaluation list. Parameter behavior: - required if configuring Host tags This parameter is not supported if configuring the widget on a template dashboard. |
|
| Marker | 0 | ds.0.marker | 0 - (default) Ellipse; 1 - Square; 2 - Triangle; 3 - Diamond; 4 - Star; 5 - Cross. |
|
| Marker size | 0 | ds.0.marker_size | 0 - (default) Small (6px); 1 - Medium (9px); 2 - Large (15px). |
|
| Time shift | 1 | ds.0.timeshift | Valid time string (e.g., 3600, 1h, etc.).You may use time suffixes. Negative values are also allowed. Default: "" (empty). |
|
| Aggregation interval | 1 | ds.0.aggregate_interval | Valid time string (e.g., 3600, 1h, etc.).You may use time suffixes. Default: 15m. |
|
| Aggregation function | 0 | ds.0.aggregate_function | 0 - not used; 1 - min; 2 - max; 3 - (default) avg; 4 - count; 5 - sum; 6 - first; 7 - last. |
|
Display options
The following parameters are supported for configuring Display options.
| Parameter | type | name | value |
|---|---|---|---|
| History data selection | 0 | source | 0 - (default) Auto; 1 - History; 2 - Trends. |
Time period
The following parameters are supported for configuring Time period.
| Parameter | type | name | value | |
|---|---|---|---|---|
| Time period | 1 | time_period._reference | DASHBOARD._timeperiod - set the dashboard time period selector as the data source;ABCDE._timeperiod - set a compatible widget (with its Reference parameter set to "ABCDE") as the data source.Default: DASHBOARD._timeperiodAlternatively, you can set the time period only in the From and To parameters. |
|
| From | 1 | time_period.from | Valid time string in absolute (YYYY-MM-DD hh:mm:ss) or relative time syntax (now, now/d, now/w-1w, etc.).Parameter behavior: - supported if Time period is not set |
|
| To | 1 | time_period.to | Valid time string in absolute (YYYY-MM-DD hh:mm:ss) or relative time syntax (now, now/d, now/w-1w, etc.).Parameter behavior: - supported if Time period is not set |
|
Axes
The following parameters are supported for configuring Axes.
| Parameter | type | name | value |
|---|---|---|---|
| X-Axis | 0 | x_axis | 0 - Disabled; 1 - (default) Enabled. |
| Y-Axis | 0 | y_axis | 0 - (default) Disabled; 1 - Enabled. |
| Min | 1 | x_axis_min | Any numeric value. Default: "" (empty). |
| y_axis_min | |||
| Max | 1 | x_axis_max | Any numeric value. Default: "" (empty). |
| y_axis_max | |||
| Units (type) | 0 | x_axis_units | 0 - (default) Auto; 1 - Static. |
| y_axis_units | |||
| Units (value) | 1 | x_axis_static_units | Any string value. Default: "" (empty). |
| y_axis_static_units |
Legend
The following parameters are supported for configuring Legend.
| Parameter | type | name | value |
|---|---|---|---|
| Show legend | 0 | legend | 0 - Disabled; 1 - (default) Enabled. |
| Show aggregation function | 0 | legend_aggregation | 0 - (default) Disabled; 1 - Enabled. Parameter behavior: - supported if Show legend is set to "Enabled" |
| Rows | 0 | legend_lines_mode | 0 - (default) Fixed; 1 - Variable. Parameter behavior: - supported if Show legend is set to "Enabled" |
| Number of rows/ Maximum number of rows |
0 | legend_lines | Possible values range: 1-10. Default: 1. Parameter behavior: - supported if Show legend is set to "Enabled" |
| Number of columns | 0 | legend_columns | Possible values range: 1-4. Default: 4. Parameter behavior: - supported if Show legend is set to "Enabled" |
Thresholds
The following parameters are supported for configuring Thresholds.
The number in the Thresholds property name (e.g., thresholds.0.color) references the threshold place in a list, sorted in ascending order. However, if thresholds are configured in a different order, the values will be sorted in ascending order after updating widget configuration in Zabbix frontend (e.g., "thresholds.0.threshold":"5" → "thresholds.0.threshold":"1"; "thresholds.1.threshold":"1" → "thresholds.1.threshold": "5").
| Parameter | type | name | value |
|---|---|---|---|
| Color interpolation | 0 | interpolation | 0 - (default) Disabled; 1 - Enabled. |
| Color | 1 | thresholds.0.color | Hexadecimal color code (e.g., FF0000). |
| X-Axis | 1 | thresholds.0.x_axis_threshold | Any numeric value. Suffixes (e.g., "1d", "2w", "4K", "8G") are supported. |
| Y-Axis | 1 | thresholds.0.y_axis_threshold | Any numeric value. Suffixes (e.g., "1d", "2w", "4K", "8G") are supported. |
Examples
The following examples aim to only describe the configuration of the dashboard widget field objects for the Scatter plot widget. For more information on configuring a dashboard, see dashboard.create.
Configuring a Scatter plot widget
Configure a Scatter plot widget in the following way:
- 5 data sets of type "Item patterns", each with default aggregation (avg, 15m) and different markers.
- The legend displays configured items in a single row and two columns.
- Thresholds are configured to color a marker red when its value reaches 80 on any axis.
{
"jsonrpc": "2.0",
"method": "dashboard.create",
"params": {
"name": "My dashboard",
"display_period": 30,
"auto_start": 1,
"pages": [
{
"widgets": [
{
"type": "scatterplot",
"name": "Scatter plot",
"x": 0,
"y": 0,
"width": 36,
"height": 5,
"view_mode": 0,
"fields": [
{
"type": 1,
"name": "ds.0.color",
"value": "0C5A87"
},
{
"type": 1,
"name": "ds.0.hosts.0",
"value": "de-frankfurt*"
},
{
"type": 1,
"name": "ds.0.x_axis_items.0",
"value": "Memory utilization"
},
{
"type": 1,
"name": "ds.0.y_axis_items.0",
"value": "CPU utilization"
},
{
"type": 0,
"name": "ds.0.marker",
"value": 0
},
{
"type": 0,
"name": "ds.0.marker_size",
"value": 1
},
{
"type": 1,
"name": "ds.1.color",
"value": "66B0D9"
},
{
"type": 1,
"name": "ds.1.hosts.0",
"value": "fr-paris*"
},
{
"type": 1,
"name": "ds.1.x_axis_items.0",
"value": "Memory utilization"
},
{
"type": 1,
"name": "ds.1.y_axis_items.0",
"value": "CPU utilization"
},
{
"type": 0,
"name": "ds.1.marker",
"value": 1
},
{
"type": 0,
"name": "ds.1.marker_size",
"value": 1
},
{
"type": 1,
"name": "ds.2.color",
"value": "0A466A"
},
{
"type": 1,
"name": "ds.2.hosts.0",
"value": "lv-riga*"
},
{
"type": 1,
"name": "ds.2.x_axis_items.0",
"value": "Memory utilization"
},
{
"type": 1,
"name": "ds.2.y_axis_items.0",
"value": "CPU utilization"
},
{
"type": 0,
"name": "ds.2.marker",
"value": 2
},
{
"type": 0,
"name": "ds.2.marker_size",
"value": 1
},
{
"type": 1,
"name": "ds.3.color",
"value": "3394C3"
},
{
"type": 1,
"name": "ds.3.hosts.0",
"value": "pl-warsaw*"
},
{
"type": 1,
"name": "ds.3.x_axis_items.0",
"value": "Memory utilization"
},
{
"type": 1,
"name": "ds.3.y_axis_items.0",
"value": "CPU utilization"
},
{
"type": 0,
"name": "ds.3.marker",
"value": 3
},
{
"type": 0,
"name": "ds.3.marker_size",
"value": 1
},
{
"type": 1,
"name": "ds.4.color",
"value": "1492C8"
},
{
"type": 1,
"name": "ds.4.hosts.0",
"value": "se-stockholm*"
},
{
"type": 1,
"name": "ds.4.x_axis_items.0",
"value": "Memory utilization"
},
{
"type": 1,
"name": "ds.4.y_axis_items.0",
"value": "CPU utilization"
},
{
"type": 0,
"name": "ds.4.marker",
"value": 4
},
{
"type": 0,
"name": "ds.4.marker_size",
"value": 1
},
{
"type": 0,
"name": "legend_columns",
"value": 2
},
{
"type": 0,
"name": "interpolation",
"value": 1
},
{
"type": 1,
"name": "thresholds.0.color",
"value": "D40000"
},
{
"type": 1,
"name": "thresholds.0.x_axis_threshold",
"value": "80"
},
{
"type": 1,
"name": "thresholds.0.y_axis_threshold",
"value": ""
},
{
"type": 1,
"name": "thresholds.1.color",
"value": "D40000"
},
{
"type": 1,
"name": "thresholds.1.x_axis_threshold",
"value": ""
},
{
"type": 1,
"name": "thresholds.1.y_axis_threshold",
"value": "80"
},
{
"type": 1,
"name": "reference",
"value": "JQISY"
}
]
}
]
}
],
"userGroups": [
{
"usrgrpid": 7,
"permission": 2
}
],
"users": [
{
"userid": 1,
"permission": 3
}
]
},
"id": 1
}Response: