Item Widgets

Create visual widgets to display real-time monitored item values directly on your network map.

What are Item Widgets?

Item widgets are standalone visual components that display real-time values from Zabbix items. Unlike monitored items on host nodes, item widgets are independent elements you can place anywhere on your map to create custom dashboards and monitoring displays.

Widget Display Types

Item widgets can display data in multiple formats:

• Number: Simple numeric display with units
• Gauge: Circular gauge with color-coded thresholds
• Bar Chart: Horizontal bar with percentage visualization
• Percentage: Percentage display with visual progress indicator

Adding an Item Widget

1. Right-click on the map canvas (not on a host)
2. Select "Add Item Widget" from the context menu
3. The Item Widget Properties dialog will open

Widget Configuration

General Settings

Host Selection

• Choose the host whose item you want to monitor
• Search by hostname for quick selection
• Only hosts on the current map's Zabbix server are available

Item Selection

• Select the specific Zabbix item to display
• Items are grouped by category for easy browsing
• Search for items by name or key

Display Type

• Choose how the value should be visualized
• Available types depend on the item's value type and units
• See Display Types below for details

Widget Label

• Custom label for the widget
• Supports Zabbix macros (see Macro Support)
• Leave blank to use the item name

Display Types

Number Display

Shows the raw value with units in a clean, readable format.

Best For:

• Counters (packets sent, requests processed)
• Absolute values (temperature, voltage)
• Values that don't have a meaningful range

Configuration:

• Font size: Adjustable
• Color: Can be set based on thresholds
• Units: Automatically displayed from Zabbix item

Gauge Display

Circular gauge with a needle indicating the current value.

Best For:

• Percentage-based metrics (CPU, memory, disk usage)
• Values with a known min/max range
• Quick visual status checks

Configuration:

• Min Value: Minimum value for the gauge (default: 0)
• Max Value: Maximum value for the gauge (default: 100)
• Thresholds: Color zones based on severity levels
• Needle Color: Color of the gauge needle

Example:

CPU Usage Gauge:
- Min: 0%
- Max: 100%
- Green zone: 0-60%
- Yellow zone: 60-80%
- Red zone: 80-100%

Bar Chart Display

Horizontal bar showing the value as a percentage of maximum.

Best For:

• Capacity metrics (disk space, bandwidth utilization)
• Progress indicators
• Comparing against limits

Configuration:

• Max Value: The 100% value for the bar
• Thresholds: Color segments based on percentage
• Show Percentage: Display percentage text
• Show Value: Display actual value

Example:

Disk Usage Bar:
- Max: Total disk space
- Current: Used space
- Bar fills from left to right
- Color changes based on usage percentage

Percentage Display

Shows the value as a percentage with a visual progress indicator.

Best For:

• Completion metrics
• Utilization percentages
• Quota tracking

Configuration:

• Calculation: Automatic from item value or custom formula
• Decimal Places: Number of decimal places to show
• Thresholds: Color coding based on percentage ranges

Threshold Configuration

Thresholds allow you to color-code widget values based on severity levels, matching Zabbix's problem severity system.

Severity Levels:

Severity	Color	Typical Use
Information	Blue	Normal operation, informational values
Warning	Yellow	Minor issues, approaching limits
Average	Orange	Moderate issues, attention needed
High	Red	Serious issues, immediate attention
Disaster	Dark Red	Critical issues, emergency response

Configuring Thresholds:

1. In the widget properties, go to the "Thresholds" tab
2. Click "Add Threshold"
3. Set the threshold value
4. Select the severity level
5. The widget will automatically use the corresponding color

Example Threshold Setup:

CPU Usage Widget:
- 0-60%: Information (Blue)
- 60-80%: Warning (Yellow)
- 80-90%: Average (Orange)
- 90-95%: High (Red)
- 95-100%: Disaster (Dark Red)

Macro Support

Widget labels support Zabbix macros for dynamic text:

Supported Macros:

• {HOST.NAME} - Host name
• {HOST.HOST} - Host technical name
• {ITEM.NAME} - Item name
• {ITEM.KEY} - Item key
• {$MACRO} - User-defined macros

Example Labels:

{HOST.NAME} - CPU Usage
{HOST.NAME} Temperature
Bandwidth: {ITEM.NAME}
{$LOCATION} - {HOST.NAME}

The macros are resolved in real-time and updated automatically.

Multi-Item Widgets

Compare multiple items in a single widget for side-by-side analysis.

Creating a Multi-Item Widget

1. Right-click on the map canvas
2. Select "Add Multi-Item Widget"
3. Add multiple items from the same or different hosts

Use Cases

Comparing Similar Metrics:

• CPU usage across multiple servers
• Network traffic on different interfaces
• Temperature sensors in different locations

Related Metrics:

• Disk read and write operations
• Inbound and outbound bandwidth
• Request rate and error rate

Cluster Monitoring:

• Database cluster node status
• Load balancer backend health
• Container resource usage

Configuration

Multi-item widgets support:

• Up to 10 items per widget
• Mixed display types (all items use the same type)
• Individual thresholds per item
• Shared or individual scales

Widget Positioning and Styling

Moving Widgets

• Click and drag widgets to reposition them
• Use arrow keys for fine-tuned positioning
• Snap to grid (if enabled in map settings)

Resizing Widgets

• Drag the corners or edges to resize
• Maintain aspect ratio (hold Shift while dragging)
• Different display types have different optimal sizes

Styling Options

Background:

• Solid color
• Transparent
• Gradient (premium feature)

Border:

• Border width
• Border color
• Border radius (rounded corners)

Font:

• Font family
• Font size
• Font weight
• Font color

Widget Management

Editing Widgets

1. Right-click on a widget
2. Select "Properties"
3. Make your changes
4. Click "Save"

Deleting Widgets

1. Right-click on a widget
2. Select "Delete"
3. Confirm the deletion

Duplicating Widgets

1. Right-click on a widget
2. Select "Duplicate"
3. A copy is created slightly offset from the original
4. Modify as needed

Best Practices

Widget Placement

1. Group Related Widgets

   • Place related metrics near each other
   • Use visual grouping (backgrounds, borders)
   • Create logical sections on your map

2. Avoid Clutter

   • Don't overcrowd the map with too many widgets
   • Use multi-item widgets to consolidate similar metrics
   • Consider creating separate dashboard maps

3. Strategic Positioning

   • Place critical metrics in prominent positions
   • Use corners for supplementary information
   • Keep important widgets visible without scrolling

Display Type Selection

Use Number Display When:

• The exact value is important
• There's no meaningful range or limit
• You're displaying counters or absolute values

Use Gauge Display When:

• Visual status is more important than exact value
• The metric has a clear min/max range
• You want quick at-a-glance monitoring

Use Bar Chart When:

• Showing capacity or utilization
• Comparing against a maximum value
• Progress tracking is important

Use Percentage When:

• The metric is naturally a percentage
• You want to emphasize the proportion
• Quota tracking is the primary concern

Threshold Configuration

1. Align with Zabbix Triggers

   • Match widget thresholds to your Zabbix trigger thresholds
   • Ensures consistency between visual indicators and alerts
   • Reduces confusion about problem severity

2. Use Meaningful Ranges

   • Don't make thresholds too sensitive
   • Allow for normal fluctuations
   • Base thresholds on historical data and baselines

3. Color Consistency

   • Use the same color scheme across all widgets
   • Follow Zabbix severity colors
   • Maintain consistency with your organization's standards

Performance Considerations

1. Limit Widget Count

   • Too many widgets can impact map performance
   • Recommended: 20-30 widgets per map maximum
   • Create separate maps for different monitoring areas

2. Update Intervals

   • Widgets update based on Zabbix item update intervals
   • Don't create items with very short intervals just for widgets
   • Balance real-time needs with system load

3. Complex Calculations

   • Avoid complex calculated items if possible
   • Use Zabbix preprocessing when needed
   • Consider caching for expensive calculations

Troubleshooting

Widget Shows "No Data"

Possible Causes:

• Item has no recent data
• Zabbix agent is not responding
• Item is disabled in Zabbix

Solutions:

• Check Zabbix item status
• Verify host is being monitored
• Check Zabbix agent connectivity

Widget Not Updating

Possible Causes:

• Map is not in focus
• Browser tab is inactive
• Network connectivity issues

Solutions:

• Refresh the map
• Check browser console for errors
• Verify Zabbix API connectivity

Incorrect Threshold Colors

Possible Causes:

• Thresholds configured incorrectly
• Value type mismatch
• Macro resolution issues

Solutions:

• Review threshold configuration
• Check item value type in Zabbix
• Verify macros are resolving correctly

Widget Performance Issues

Possible Causes:

• Too many widgets on the map
• Complex calculated items
• High-frequency item updates

Solutions:

• Reduce widget count
• Simplify calculations
• Increase item update intervals
• Split into multiple maps

Examples

Server Monitoring Dashboard

Create a comprehensive server monitoring view:

Widgets to Add:
1. CPU Usage (Gauge) - 0-100%
2. Memory Usage (Bar Chart) - Used/Total
3. Disk Space (Percentage) - Used percentage
4. Network Traffic (Multi-item) - RX/TX rates
5. System Load (Number) - Load average
6. Uptime (Number) - Days/hours

Network Overview

Monitor network infrastructure:

Widgets to Add:
1. Total Bandwidth (Bar Chart) - Utilization percentage
2. Active Connections (Number) - Connection count
3. Packet Loss (Gauge) - Loss percentage
4. Latency (Number) - Response time
5. Error Rate (Percentage) - Errors/total packets

Application Performance

Track application metrics:

Widgets to Add:
1. Request Rate (Number) - Requests per second
2. Response Time (Gauge) - Average response time
3. Error Rate (Percentage) - 4xx/5xx errors
4. Active Users (Number) - Current users
5. Database Connections (Bar Chart) - Used/available

Related Features

• Monitored Items: See Adding Hosts
• Graphs: See Adding Hosts
• Thresholds: Align with Zabbix trigger configuration

tip

Item widgets are perfect for creating dedicated monitoring dashboards. Create a separate map just for widgets to have a comprehensive overview of your infrastructure's health!