Table of Contents
7 Gauge
Description
These parameters and the possible property values for the respective dashboard widget field objects allow to configure the Gauge 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 Gauge widget, please refer to the parameter behavior outlined in the tables below.
Parameters
The following parameters are supported for the Gauge 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. |
|
| Item | 4 | itemid.0 | Item ID. Parameter behavior: - required if Item (Widget) is not set |
|
| Item (Widget) | 1 | itemid._reference | Instead of Item ID:ABCDE._itemid - set a compatible widget (with its Reference parameter set to "ABCDE") as the data source for items.Parameter behavior: - required if Item is not set |
|
| Min | 1 | min | Any numeric value. Suffixes (e.g. "1d", "2w", "4K", "8G") are supported. Default: "0". |
|
| Max | 1 | max | Any numeric value. Suffixes (e.g. "1d", "2w", "4K", "8G") are supported. Default: "100". |
|
| Value arc | 1 | value_arc_color | Hexadecimal color code (e.g. FF0000).Default: "" (empty). |
|
| Arc background | 1 | empty_color | Hexadecimal color code (e.g. FF0000).Default: "" (empty). |
|
| Background | 1 | bg_color | Hexadecimal color code (e.g. FF0000).Default: "" (empty). |
|
| Show | 0 | show.0 | 1 - Description; 2 - Value; 3 - Needle; 4 - Scale; 5 - Value arc. Note: To configure multiple values, create a dashboard widget field object for each value with an incremented number in the property name. Default: 1, 2, 4, 5. Values "Needle" and "Scale" are not supported if both: - no dashboard widget field object for Show with the value "Value arc" is set; - Show arc advanced configuration parameter is set to "Disabled". Advanced configuration parameters for Show options are not supported if no dashboard widget field objects with the respective values are set. |
|
| Override host | 1 | 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. |
|
Advanced configuration
The following advanced configuration parameters are supported for the Gauge widget.
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 |
|---|---|---|---|
| Angle | 0 | angle | Possible values: 180 (default) or 270. |
| Description | |||
| Description | 1 | description | Any string value, including macros. Supported macros: {HOST.*}, {ITEM.*}, {INVENTORY.*}, user macros. Default: {ITEM.NAME}. |
| Size | 0 | desc_size | Possible values range from 1-100. Default: 15. |
| Vertical position | 0 | desc_v_pos | 0 - Top; 1 - (default) Bottom. |
| Bold | 0 | desc_bold | 0 - (default) Disabled; 1 - Enabled. |
| Color | 1 | desc_color | Hexadecimal color code (e.g. FF0000).Default: "" (empty). |
| Value | |||
| Decimal places | 0 | decimal_places | Possible values range from 1-10. Default: 2. |
| Size | 0 | value_size | Possible values range from 1-100. Default: 25. |
| Bold | 0 | value_bold | 0 - (default) Disabled; 1 - Enabled. |
| Color | 1 | value_color | Hexadecimal color code (e.g. FF0000).Default: "" (empty). |
| Units | |||
| Units (checkbox) | 0 | units_show | 0 - Disabled; 1 - (default) Enabled. |
| Units (value) | 1 | units | Any string value. Parameter behavior: - supported if Units (checkbox) is set to "Enabled" |
| Size | 0 | units_size | Possible values range from 1-100. Default: 25. Parameter behavior: - supported if Units (checkbox) is set to "Enabled" |
| Bold | 0 | units_bold | 0 - (default) Disabled; 1 - Enabled. Parameter behavior: - supported if Units (checkbox) is set to "Enabled" |
| Position | 0 | units_pos | 0 - Before value; 1 - Above value; 2 - (default) After value; 3 - Below value. Parameter behavior: - supported if Units (checkbox) is set to "Enabled" This parameter is ignored if set to one of the following time-related units: unixtime, uptime, s. |
| Color | 1 | units_color | Hexadecimal color code (e.g. FF0000).Default: "" (empty). |
| Value arc | |||
| Arc size | 0 | value_arc_size | Possible values range from 1-100. Default: 20. |
| Needle | |||
| Color | 1 | needle_color | Hexadecimal color code (e.g. FF0000).Default: "" (empty).Parameter behavior: - supported if a dashboard widget field object for Show with the value "Value arc" is set, or Show arc is set to "Enabled" |
| Scale | |||
| Show units | 0 | scale_show_units | 0 - Disabled; 1 - (default) Enabled. Parameter behavior: - supported if Units (checkbox) is set to "Enabled" and either a dashboard widget field object for Show with the value "Value arc" is set, or Show arc is set to "Enabled" |
| Size | 0 | scale_size | Possible values range from 1-100. Default: 15. Parameter behavior: - supported if a dashboard widget field object for Show with the value "Value arc" is set, or Show arc is set to "Enabled" |
| Decimal places | 0 | scale_decimal_places | Possible values range from 1-10. Default: 0. Parameter behavior: - supported if a dashboard widget field object for Show with the value "Value arc" is set, or Show arc is set to "Enabled" |
| Thresholds | |||
| Color | 1 | thresholds.0.color | Hexadecimal color code (e.g. FF0000). |
| Threshold | 1 | thresholds.0.threshold | Any numeric value. Suffixes (e.g. "1d", "2w", "4K", "8G") are supported. |
| Show labels | 0 | th_show_labels | 0 - (default) Disabled; 1 - Enabled. Parameter behavior: - supported if Thresholds are set and either a dashboard widget field object for Show with the value "Value arc" is set or Show arc is set to "Enabled" |
| Show arc | 0 | th_show_arc | 0 - (default) Disabled; 1 - Enabled. Parameter behavior: - supported if Thresholds are set |
| Arc size | 0 | th_arc_size | Possible values range from 1-100. Default: 5. Parameter behavior: - supported if Show arc is set to "Enabled" |
Examples
The following examples aim to only describe the configuration of the dashboard widget field objects for the Gauge widget. For more information on configuring a dashboard, see dashboard.create.
Configuring a Gauge widget
Configure a Gauge widget that displays the item value for the item "44474" (Interface enp0s3: Bits sent). In addition, visually fine-tune the widget with multiple advanced options, including thresholds.
{
"jsonrpc": "2.0",
"method": "dashboard.create",
"params": {
"name": "My dashboard",
"display_period": 30,
"auto_start": 1,
"pages": [
{
"widgets": [
{
"type": "gauge",
"name": "Gauge",
"x": 0,
"y": 0,
"width": 18,
"height": 5,
"view_mode": 0,
"fields": [
{
"type": 4,
"name": "itemid.0",
"value": 44474
},
{
"type": 1,
"name": "min",
"value": "100000"
},
{
"type": 1,
"name": "max",
"value": "1000000"
},
{
"type": 0,
"name": "show.0",
"value": 1
},
{
"type": 0,
"name": "show.1",
"value": 2
},
{
"type": 0,
"name": "show.2",
"value": 3
},
{
"type": 0,
"name": "show.4",
"value": 4
},
{
"type": 0,
"name": "show.5",
"value": 5
},
{
"type": 0,
"name": "angle",
"value": 270
},
{
"type": 0,
"name": "desc_size",
"value": 10
},
{
"type": 0,
"name": "desc_bold",
"value": 1
},
{
"type": 0,
"name": "decimal_places",
"value": 0
},
{
"type": 0,
"name": "value_bold",
"value": 1
},
{
"type": 0,
"name": "units_size",
"value": 15
},
{
"type": 0,
"name": "units_pos",
"value": 3
},
{
"type": 1,
"name": "needle_color",
"value": "3C3C3C"
},
{
"type": 1,
"name": "thresholds.0.color",
"value": "FF465C"
},
{
"type": 1,
"name": "thresholds.0.threshold",
"value": "700000"
},
{
"type": 1,
"name": "thresholds.1.color",
"value": "FFD54F"
},
{
"type": 1,
"name": "thresholds.1.threshold",
"value": "500000"
},
{
"type": 1,
"name": "thresholds.2.color",
"value": "0EC9AC"
},
{
"type": 1,
"name": "thresholds.2.threshold",
"value": "100000"
},
{
"type": 0,
"name": "th_show_labels",
"value": 1
},
{
"type": 0,
"name": "th_show_arc",
"value": 1
},
{
"type": 0,
"name": "th_arc_size",
"value": 15
}
]
}
]
}
],
"userGroups": [
{
"usrgrpid": 7,
"permission": 2
}
],
"users": [
{
"userid": 1,
"permission": 3
}
]
},
"id": 1
}Response: