zabbix/zabbix-graphql-api
1
0
Fork 0
Code Pull requests Activity

feat: optimize Zabbix queries and enhance specialized device support

Browse source 
- Implement query optimization (reduced output, parameter skipping) to minimize Zabbix API traffic.

- Add indirect dependency handling: deviceType implies tags and state implies items.

- Move schema extensions to samples/extensions/ to clarify their role as samples.

- Enhance DistanceTrackerDevice with String time fields to support optional date portions.

- Ensure allDevices strictly filters by deviceType and populates the field in results.

- Refactor runAllRegressionTests mutation to use internal unique names and improve stability.

- Fix unnecessary Zabbix API calls for item preprocessing during template and host imports.

- Update documentation including cookbook recipes, test specifications, and optimization guides.

- Add extensive unit, integration, and regression tests covering all implemented changes.

- Update docker-compose.yml to mount the samples/ directory as a volume.

- Update IntelliJ .idea run configurations to reflect the new sample extension paths.
This commit is contained in:
Andreas Hilbig 2026-02-02 13:20:06 +01:00
parent 97a0f70fd6
commit b646b8c606
28 changed files with 551 additions and 74 deletions
Download patch file Download diff file Expand all files Collapse all files

115
schema/extensions/display_devices.graphql
View file

@ -1,115 +0,0 @@
"""
SinglePanelDevice represents a device which can display a single picture, e.g. using LED technology.
The picture is represented either by a displaySign (a numeric value e.g. the index of the picture)
or a contentKey, which is usually the hash of the bitmap which shall be displayed.
"""
type SinglePanelDevice implements Host & Device {
hostid: ID!
"""
Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname
"""
host: String!
deviceType: String
hostgroups: [HostGroup!]
name: String
tags: DeviceConfig
inventory: Inventory
items: [ZabbixItem!]
state: PanelState
}
"""
Represents the state of a single panel device.
"""
type PanelState implements DeviceState {
"""Operational data (telemetry)."""
operational: OperationalDeviceData
"""Current display state."""
current: PanelCurrentState
}
"""
Represents the current state of a panel.
"""
type PanelCurrentState {
"""The current values being displayed on the panel."""
values: PanelValues
}
"""
Specific values displayed on a panel.
"""
type PanelValues {
"""
Index of the bitmap which is displayed.
"""
contentIndex: Int
"""
Hash of the bitmap which is displayed.
"""
contentKey: String
"""
Text representation of what is displayed.
"""
contentText: String
}
"""
The FourPanelDevice is a panel which allows to define pictures in 4
subpanels, called TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT.
"""
type FourPanelDevice implements Host & Device {
"""Internal Zabbix ID of the device."""
hostid: ID!
"""
Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname.
"""
host: String!
"""Classification of the device."""
deviceType: String
"""List of host groups this device belongs to."""
hostgroups: [HostGroup!]
"""Visible name of the device."""
name: String
"""Device configuration tags."""
tags: DeviceConfig
"""Host inventory data."""
inventory: Inventory
"""List of monitored items for this host."""
items: [ZabbixItem!]
"""State of the four-panel device."""
state: FourPanelState
}
"""
Represents the state of a four-panel device.
"""
type FourPanelState implements DeviceState {
"""Operational data (telemetry)."""
operational: OperationalDeviceData
"""Current state of all four panels."""
current: FourPanelCurrentState
}
"""
Represents the combined current state of four panels.
"""
type FourPanelCurrentState {
"""The values for each of the four panels."""
values: FourPanelValues
}
"""
Values for each of the four panels in a FourPanelDevice.
"""
type FourPanelValues {
"""State of the top-left panel."""
TOP_LEFT: PanelValues
"""State of the top-right panel."""
TOP_RIGHT: PanelValues
"""State of the bottom-left panel."""
BOTTOM_LEFT: PanelValues
"""State of the bottom-right panel."""
BOTTOM_RIGHT: PanelValues
}

46
schema/extensions/ground_value_checker.graphql
View file

@ -1,46 +0,0 @@
"""
GroundValueChecker represents a device that retrieves ground values
from public APIs (e.g. BORIS NRW) using Zabbix HTTP agent items.
"""
type GroundValueChecker implements Host & Device {
"""Internal Zabbix ID of the device."""
hostid: ID!
"""
Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname.
"""
host: String!
"""Classification of the device."""
deviceType: String
"""List of host groups this device belongs to."""
hostgroups: [HostGroup!]
"""Visible name of the device."""
name: String
"""Device configuration tags."""
tags: DeviceConfig
"""Host inventory data."""
inventory: Inventory
"""List of monitored items for this host."""
items: [ZabbixItem!]
"""State of the ground value checker device."""
state: GroundValueState
}
"""
Represents the state of a ground value checker device.
"""
type GroundValueState implements DeviceState {
"""Operational data (telemetry)."""
operational: OperationalDeviceData
"""Current business values (ground data)."""
current: GroundValues
}
"""
Aggregated ground information retrieved from the API.
"""
type GroundValues {
"""
Average ground value (in €/m²). Extracted from the BORIS NRW GeoJSON response.
"""
averageValue: Float
}

74
schema/extensions/location_tracker_commons.graphql
View file

@ -1,74 +0,0 @@
"""
Represents the payload for a sensor distance measurement.
"""
type SensorDistanceValue implements DeviceValue {
"""
Represents the name of the device that reports or provides distance sensor data.
Uniquely identifies the device within the context of the SensorDistanceValue.
"""
deviceName: String
"""
Represents the MAC address of the device. Typically formatted as a 12-character
hexadecimal string (e.g. "00:1A:2B:3C:4D:5E").
"""
mac: String
"""
Represents the measured or calculated distance value, typically in meters.
Should be non-negative.
"""
distance: Float
"""
Represents the time at which the sensor measurement was recorded.
"""
time: String
"""
Dummy field to allow for empty interfaces.
"""
_empty: String
}
"""
Represents a coordinate in 3D space with x, y, and z components.
"""
type Position {
"""X coordinate."""
x: Float
"""Y coordinate."""
y: Float
"""Z coordinate."""
z: Float
}
"""
Represents the result of a position calculation, including the calculated position and accuracy.
"""
type PositionCalculatorResult {
"""The calculated 3D position."""
position: Position
"""The estimated accuracy of the calculation."""
accuracy: Float
}
"""
Concrete implementation of a DeviceValueMessage for sensor distance data.
"""
type SensorDistanceMessage implements DeviceValueMessage {
"""The unique identifier of the device."""
deviceKey: String
"""Timestamp of the message."""
timestamp: String
"""Name of the attribute."""
attributeName: String
"""Name of the topic."""
topicName: String
"""Type of the device."""
deviceType: String
"""The sensor distance value payload."""
value: SensorDistanceValue
}

59
schema/extensions/location_tracker_devices.graphql
View file

@ -1,59 +0,0 @@
"""
DistanceTracker represents a device which can detect other devices around itself and estimate
the distances, e.g. by using Bluetooth scanning technology and estimating the distance.
"""
type DistanceTrackerDevice implements Host & Device {
"""Internal Zabbix ID of the device."""
hostid: ID!
"""
Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname.
"""
host: String!
"""Classification of the device."""
deviceType: String
"""List of host groups this device belongs to."""
hostgroups: [HostGroup!]
"""Visible name of the device."""
name: String
"""Device configuration tags."""
tags: DeviceConfig
"""Host inventory data."""
inventory: Inventory
"""List of monitored items for this host."""
items: [ZabbixItem!]
"""State of the distance tracker device."""
state: DistanceTrackerState
}
"""
Represents the state of a distance tracker device.
"""
type DistanceTrackerState implements DeviceState {
"""Operational data (telemetry)."""
operational: OperationalDeviceData
"""Current business values (detected devices and distances)."""
current: DistanceTrackerValues
}
"""
Aggregated information of devices detected around the tracker.
"""
type DistanceTrackerValues {
"""
Start of time interval for the delivered device counting value.
"""
timeFrom: Time
"""
End of time interval for the delivered device counting value.
"""
timeUntil: Time
"""
Number of unique device keys detected between timeFrom and timeUntil.
"""
count: Int
"""
Detailed information about devices detected nearby.
"""
distances: [SensorDistanceValue!]
}

50
schema/extensions/weather_sensor.graphql
View file

@ -1,50 +0,0 @@
"""
WeatherSensorDevice represents a device that retrieves weather information
from public APIs (e.g. Open-Meteo) using Zabbix HTTP agent items.
"""
type WeatherSensorDevice implements Host & Device {
"""Internal Zabbix ID of the device."""
hostid: ID!
"""
Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname.
"""
host: String!
"""Classification of the device."""
deviceType: String
"""List of host groups this device belongs to."""
hostgroups: [HostGroup!]
"""Visible name of the device."""
name: String
"""Device configuration tags."""
tags: DeviceConfig
"""Host inventory data."""
inventory: Inventory
"""List of monitored items for this host."""
items: [ZabbixItem!]
"""State of the weather sensor device."""
state: WeatherSensorState
}
"""
Represents the state of a weather sensor device.
"""
type WeatherSensorState implements DeviceState {
"""Operational data (telemetry)."""
operational: OperationalDeviceData
"""Current business values (weather data)."""
current: WeatherSensorValues
}
"""
Aggregated weather information retrieved from the API.
"""
type WeatherSensorValues {
"""
Current temperature at the device location (in °C).
"""
temperature: Float
"""
Warnings or description of the street conditions (e.g. Ice, Rain, Clear). Derived from Open-Meteo weather codes.
"""
streetConditionWarnings: String
}

7
schema/mutations.graphql
View file

@ -142,12 +142,7 @@ type Mutation {
"""
Runs all regression tests.
"""
runAllRegressionTests(
"""Technical name for the test host."""
hostName: String!,
"""Technical name for the test host group."""
groupName: String!
): SmoketestResponse!
runAllRegressionTests: SmoketestResponse!
}
"""