20 Pie chart

Description

These parameters and the possible property values for the respective dashboard widget field objects allow to configure the Pie chart 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 Pie chart widget, please refer to the parameter behavior outlined in the tables below.

Parameters

The following parameters are supported for the Pie chart 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.

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.
Items 4 ds.0.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 Items (Widget) is not set
Items (Widget) 1 ds.0.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.

This parameter is supported since Zabbix 7.0.1.

Parameter behavior:
- required if Data set type is set to "Item list" and Items is not set
Color 1 ds.0.color.0 Hexadecimal color code (e.g. FF0000).

Parameter behavior:
- supported if Data set type is set to "Item list"
Item type 0 ds.0.type.0 0 - (default) Normal;
1 - Total.

The value "Total" can be set only for one item in the whole chart.

Parameter behavior:
- supported if Data set type is set to "Item list"
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.
Item patterns 1 ds.0.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"
Color 1 ds.0.color Hexadecimal color code (e.g. FF0000).

Parameter behavior:
- supported if Data set type is set to "Item patterns"
Aggregation function 0 ds.0.aggregate_function 1 - min;
2 - max;
3 - avg;
4 - count;
5 - sum;
6 - first;
7 - (default) last.
Data set aggregation 0 ds.0.dataset_aggregation 0 - (default) none;
1 - min;
2 - max;
3 - avg;
4 - count;
5 - sum.

Parameter behavior:
- supported if Item type is set to "Total"
Data set label 1 ds.0.data_set_label Any string value.

Default: "" (empty).

Displaying options

The following parameters are supported for configuring Displaying options.

Parameter type name value
History data selection 0 source 0 - (default) Auto;
1 - History;
2 - Trends.
Draw 0 draw_type 0 - (default) Pie;
1 - Doughnut.
Width 0 width 20 - 20% of the radius;
30 - 30% of the radius;
40 - 40% of the radius;
50 - (default) 50% of the radius.

Parameter behavior:
- supported if Draw is set to "Doughnut"
Stroke width 0 stroke Possible values range from 0-10.

Default: 0.

This parameter is supported since Zabbix 7.0.1.

Parameter behavior:
- supported if Draw is set to "Doughnut"
Show total value 0 total_show 0 - (default) Disabled;
1 - Enabled.

Parameter behavior:
- supported if Draw is set to "Doughnut"
Size 0 value_size_type 0 - (default) Auto;
1 - Custom.

Parameter behavior:
- supported if Show total value is set to "Enabled"
Size (value for custom size) 0 value_size Possible values range from 1-100.

Default: 20.

Parameter behavior:
- supported if Show total value is set to "Enabled"
Decimal places 0 decimal_places Possible values range from 0-6.

Default: 2.

Parameter behavior:
- supported if Show total value is set to "Enabled"
Units (checkbox) 0 units_show 0 - (default) Disabled;
1 - Enabled.

Parameter behavior:
- supported if Show total value is set to "Enabled"
Units (value) 1 units Any string value.

Parameter behavior:
- supported if Units (checkbox) is set to "Enabled"
Bold 0 value_bold 0 - (default) Disabled;
1 - Enabled.

Parameter behavior:
- supported if Show total value is set to "Enabled"
Color 1 value_color Hexadecimal color code (e.g. FF0000).

Parameter behavior:
- supported if Show total value is set to "Enabled"
Space between sectors 0 space Possible values range from 0-10.

Default: 1.
Merge sectors smaller than N% (checkbox) 0 merge 0 - (default) Disabled;
1 - Enabled.
Merge sectors smaller than N% (value) 0 merge_percent Possible values range from 1-10.

Default: 1.

Parameter behavior:
- supported if Merge sectors smaller than N% (checkbox) is set to "Enabled"
Merge sectors smaller than N% (color) 1 merge_color Hexadecimal color code (e.g. FF0000).

Parameter behavior:
- supported if Merge sectors smaller than N% (checkbox) is set to "Enabled"

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 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._timeperiod

Alternatively, 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

Legend

The following parameters are supported for configuring Legend.

Parameter type name value
Show legend 0 legend 0 - Disabled;
1 - (default) Enabled.
Show value 0 legend_value 0 - (default) Disabled;
1 - Enabled.

Parameter behavior:
- supported if Show legend is set to "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 from 1-10.

Default: 1.

Parameter behavior:
- supported if Show legend is set to "Enabled"
Number of columns 0 legend_columns Possible values range from 1-4.

Default: 4.

Parameter behavior:
- supported if Show legend is set to "Enabled", and Show value is set to "Disabled"

Examples

The following examples aim to only describe the configuration of the dashboard widget field objects for the Pie chart widget. For more information on configuring a dashboard, see dashboard.create.

Configuring a Pie chart widget

Configure a Pie chart widget in the following way:

  • 2 data sets for a total of 9 items on 1 host.
  • The first data set is of type "Item list" and consists of 3 items that are all with type "Normal" and represented by a different color.
  • The second data set is of type "Item patterns", consists of 6 items, has a configured aggregation for each item, and is represented by a custom color.
  • The second data set also has a custom data set label.
  • Data in the pie chart are displayed as a doughnut chart with a custom width and total value with units in the center.
  • Data in the pie chart are displayed and aggregated for a custom time period of the last 3 hours.
  • Pie chart legend displays configured items in 4 rows.

Request:

{
           "jsonrpc": "2.0",
           "method": "dashboard.create",
           "params": {
               "name": "My dashboard",
               "display_period": 30,
               "auto_start": 1,
               "pages": [
                   {
                       "widgets": [
                           {
                               "type": "piechart",
                               "name": "Pie chart",
                               "x": 0,
                               "y": 0,
                               "width": 24,
                               "height": 5,
                               "view_mode": 0,
                               "fields": [
                                   {
                                       "type": 0,
                                       "name": "ds.0.dataset_type",
                                       "value": 0
                                   },
                                   {
                                       "type": 4,
                                       "name": "ds.0.itemids.1",
                                       "value": 23264
                                   },
                                   {
                                       "type": 1,
                                       "name": "ds.0.color.1",
                                       "value": "FF0000"
                                   },
                                   {
                                       "type": 0,
                                       "name": "ds.0.type.1",
                                       "value": 0
                                   },
                                   {
                                       "type": 4,
                                       "name": "ds.0.itemids.2",
                                       "value": 23269
                                   },
                                   {
                                       "type": 1,
                                       "name": "ds.0.color.2",
                                       "value": "BF00FF"
                                   },
                                   {
                                     "type": 0,
                                     "name": "ds.0.type.2",
                                     "value": 0
                                   },
                                   {
                                       "type": 4,
                                       "name": "ds.0.itemids.3",
                                       "value": 23257
                                   },
                                   {
                                       "type": 1,
                                       "name": "ds.0.color.3",
                                       "value": "0040FF"
                                   },
                                   {
                                     "type": 0,
                                     "name": "ds.0.type.3",
                                     "value": 0
                                   },
                                   {
                                       "type": 1,
                                       "name": "ds.1.hosts.0",
                                       "value": "Zabbix server"
                                   },
                                   {
                                       "type": 1,
                                       "name": "ds.1.items.0",
                                       "value": "*: Number of processed *values per second"
                                   },
                                   {
                                       "type": 1,
                                       "name": "ds.1.color",
                                       "value": "000000"
                                   },
                                   {
                                       "type": 0,
                                       "name": "ds.1.aggregate_function",
                                       "value": 3
                                   },
                                   {
                                       "type": 1,
                                       "name": "ds.1.data_set_label",
                                       "value": "Number of processed values per second"
                                   },
                                   {
                                       "type": 0,
                                       "name": "draw_type",
                                       "value": 1
                                   },
                                   {
                                       "type": 0,
                                       "name": "width",
                                       "value": 30
                                   },
                                   {
                                       "type": 0,
                                       "name": "total_show",
                                       "value": 1
                                   },
                                   {
                                       "type": 0,
                                       "name": "units_show",
                                       "value": 1
                                   },
                                   {
                                       "type": 0,
                                       "name": "graph_time",
                                       "value": 1
                                   },
                                   {
                                       "type": 1,
                                       "name": "time_period.from",
                                       "value": "now-3h"
                                   },
                                   {
                                       "type": 0,
                                       "name": "legend_lines",
                                       "value": 4
                                   }
                               ]
                           }
                       ]
                   }
               ],
               "userGroups": [
                   {
                       "usrgrpid": 7,
                       "permission": 2
                   }
               ],
               "users": [
                   {
                       "userid": 1,
                       "permission": 3
                   }
               ]
           },
           "id": 1
       }

Response:

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

See also