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.

Request:

{
           "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:

{
           "jsonrpc": "2.0",
           "result": {
               "dashboardids": [
                   "3"
               ]
           },
           "id": 1
       }

See also