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

feat: implement history push mutation and enhanced MCP logging

Browse source 
- Implement pushHistory mutation to support pushing telemetry data to Zabbix trapper items.

- Add VERBOSITY and MCP_LOG_* environment variables for controllable request/response logging in both API and MCP server.

- Enhance ZabbixRESTDataSource with better session handling and error logging.

- Update ZabbixHistory datasource to support history push operations.

- Expand documentation with new cookbook recipes and MCP integration guides.

- Add integration tests for history pushing (src/test/history_push*).

- Reorganize documentation, moving technical product info PDF to docs/use-cases/.

- Update GraphQL generated types and VCR templates.
This commit is contained in:
Andreas Hilbig 2026-02-03 13:29:42 +01:00
parent b646b8c606
commit 7c2dee2b6c
28 changed files with 6036 additions and 3088 deletions
Download patch file Download diff file Expand all files Collapse all files

156
docs/howtos/cookbook.md
View file

@ -346,6 +346,91 @@ Create a host, assign it macros for coordinates, and query its state.
---
## 🍳 Recipe: Extending Schema with a Simulated Device (Zabbix Trap)
This recipe demonstrates how to create a simulated device type that receives data via Zabbix Trapper items. This is useful for testing or for devices that push their state (like Path/GeoJSON data) to Zabbix instead of being polled.
### 📋 Prerequisites
- Zabbix GraphQL API is running.
- You have an external script or system capable of pushing data to Zabbix (e.g. using `zabbix_sender` or the `pushHistory` mutation).
### 🛠️ Step 1: Define the Schema Extension
Add the `TrackedDevice` type to `samples/extensions/location_tracker_devices.graphql`:
```graphql
type TrackedDevice implements Host & Device {
hostid: ID!
host: String!
deviceType: String
hostgroups: [HostGroup!]
name: String
tags: DeviceConfig
inventory: Inventory
items: [ZabbixItem!]
state: TrackedState
}
type TrackedState implements DeviceState {
operational: OperationalDeviceData
current: TrackedValues
}
type TrackedValues {
"""
GeoJSON representation of the tracked device's location or path.
"""
geojson: JSONObject
}
```
### ⚙️ Step 2: Register the Resolver
Add `TrackedDevice` to your `.env` file:
```env
ADDITIONAL_RESOLVERS=...,TrackedDevice
```
Restart the API server.
### 🚀 Step 3: Import the Simulated Device Template
Use the `importTemplates` mutation to create a template with a **Zabbix Trapper** item. We use the `json_` prefix in the item key to ensure the JSON string is automatically parsed into a `JSONObject`.
> **Reference**: Use the [Sample: Import Simulated BT Template](../../docs/queries/sample_import_simulated_bt_template.graphql) for a complete mutation and variables example.
### 🚀 Step 4: Push History Data
Push GeoJSON data to your simulated device using the `pushHistory` mutation. This allows you to simulate a device moving along a path by providing multiple data points with different timestamps.
> **Reference**: See the [Sample: Push GeoJSON History](../../docs/queries/sample_push_geojson_history.graphql) for a complete example of pushing historical data.
### ✅ Step 5: Verification
Verify that the device correctly resolves to the new type and that both the current state and historical data are accessible.
- **Create Host**: Use the `importHosts` mutation to create a host (e.g. `Vehicle1`) and link it to the simulated template.
- **Query Current State**: Use the `allDevices` query to verify the latest pushed position.
- *Reference*: See the [Sample: Tracked Device Query](../../docs/queries/sample_tracked_device_query.graphql).
- **Query Historical Data**: Use the `exportHostValueHistory` query to retrieve the path history.
```graphql
query GetVehicleHistory($host: [String!], $key: [String!]) {
exportHostValueHistory(
host_filter: $host,
itemKey_filter: $key,
type: TEXT,
limit: 100
) {
result
}
}
```
**Variables**:
```json
{
"host": ["Vehicle1"],
"key": ["state.current.json_geojson"]
}
```
---
## 🍳 Recipe: Testing Specialized Device Types
This recipe shows how to execute a comprehensive query to verify the state and configuration of specialized device types, such as the `DistanceTrackerDevice`. This is useful for validating that your schema extensions and hierarchical mappings are working correctly.
@ -586,6 +671,77 @@ You can ask **Junie** to automate the entire cloning process:
---
## 🍳 Recipe: Pushing History Data to Trapper Items
This recipe shows how to push data into Zabbix items of type `ZABBIX_TRAP` using the `pushHistory` mutation. This is particularly useful for IoT devices or external systems that push data to Zabbix instead of being polled.
### 📋 Prerequisites
- Zabbix GraphQL API is running.
- A host exists in Zabbix.
- An item of type `ZABBIX_TRAP` (type 2) exists on that host.
### 🛠️ Step 1: Preparation
Identify the `itemid` or the combination of `host` and `key` for the target item.
### 🚀 Step 2: Execution/Action
Execute the `pushHistory` mutation. You can provide multiple values with different timestamps. The `value` field accepts a `JSONObject`, which will be automatically stringified before being sent to Zabbix.
```graphql
mutation PushDeviceData($host: String, $key: String, $itemid: Int, $values: [HistoryPushInput!]!) {
pushHistory(host: $host, key: $key, itemid: $itemid, values: $values) {
message
data {
itemid
error {
message
}
}
}
}
```
**Sample Variables**:
```json
{
"host": "IoT-Sensor-01",
"key": "sensor.data.json",
"values": [
{
"timestamp": "2024-01-01T12:00:00Z",
"value": {
"temperature": 22.5,
"humidity": 45
}
},
{
"timestamp": "2024-01-01T12:01:00Z",
"value": {
"temperature": 22.6,
"humidity": 44
}
}
]
}
```
### ✅ Step 3: Verification
Verify that the data was successfully pushed by querying the item's last value:
```graphql
query VerifyPushedData($host: String!) {
allHosts(filter_host: $host) {
items {
name
key_
lastvalue
lastclock
}
}
}
```
---
## 🍳 Recipe: Setting up GraphQL MCP for AI Agents
This recipe guides you through setting up the Model Context Protocol (MCP) server to enable AI agents like **Junie** or **Claude** to interact with your Zabbix data through the GraphQL API.

14
docs/howtos/mcp.md
View file

@ -102,3 +102,17 @@ The MCP server can be used in conjunction with the [**Cookbook**](./cookbook.md)
Example prompt for an LLM:
> "Using the `zabbix-graphql` MCP server, follow the 'Provisioning a New Host' recipe from the cookbook. Create a host named 'Test-Host-01' in the 'Linux servers' group and link the 'ICMP Ping' template."
### 📝 Logging & Verbosity
You can control the logging level and verbosity of both the GraphQL API and the MCP server via environment variables. This is particularly useful for debugging MCP calls and seeing the exact parameters and responses.
- **GraphQL API Verbosity**:
- `VERBOSITY=1`: Logs GraphQL operation names and parameters (variables).
- `VERBOSITY=2`: Logs operation names, parameters, and the full response body.
- **MCP Server Logging**:
- `MCP_LOG_LEVEL`: Sets the log level for the Apollo MCP server (`debug`, `info`, `warn`, `error`).
- `MCP_LOG_PARAMETERS=true`: Enables logging of parameters in the MCP server.
- `MCP_LOG_RESPONSES=true`: Enables logging of responses in the MCP server.
When running via Docker Compose, these can be set in your `.env` file.

3
docs/queries/README.md
View file

@ -8,12 +8,15 @@ This directory contains practical examples of GraphQL operations for the Zabbix
- [Query All Hosts](./sample_all_hosts_query.graphql): Retrieve basic host information and inventory.
- [Import Hosts](./sample_import_hosts_mutation.graphql): Create or update multiple hosts with tags and group assignments.
- [Query All Devices](./sample_all_devices_query.graphql): Query specialized devices using the `allDevices` query.
- [Tracked Device Query](./sample_tracked_device_query.graphql): Query simulated or tracked devices.
- [Push GeoJSON History](./sample_push_geojson_history.graphql): Push multiple GeoJSON data points to a tracked device.
- [Distance Tracker Test Query](./sample_distance_tracker_test_query.graphql): Comprehensive query for testing specialized `DistanceTrackerDevice` types.
### 📄 Templates
- [Query Templates](./sample_templates_query.graphql): List available templates and their items.
- [Import Templates](./sample_import_templates_mutation.graphql): Create or update complex templates with item definitions and preprocessing.
- [Import Distance Tracker Template](./sample_import_distance_tracker_template.graphql): Example of importing a template for a schema extension.
- [Import Simulated BT Template](./sample_import_simulated_bt_template.graphql): Example of importing a template for a simulated device.
- [Delete Templates](./sample_delete_templates_mutation.graphql): Remove templates by ID or name pattern.
### 📂 Template Groups

46
docs/queries/sample_import_simulated_bt_template.graphql Normal file
View file

@ -0,0 +1,46 @@
### Mutation
Use this mutation to import a template for a simulated device that pushes GeoJSON data via Zabbix Trapper items.
```graphql
mutation ImportSimulatedBTTemplate($templates: [CreateTemplate!]!) {
importTemplates(templates: $templates) {
host
templateid
message
error {
message
}
}
}
```
### Variables
The following sample defines the `SIMULATED_BT_DEVICE` template. Note the `deviceType` tag set to `TrackedDevice`, which instructs the GraphQL API to resolve this host using the specialized `TrackedDevice` type.
We use the `state.current.json_geojson` key for the trapper item. The `json_` prefix ensures that the JSON string received from Zabbix is automatically parsed into a `JSONObject` by the GraphQL resolver.
```json
{
"templates": [
{
"host": "SIMULATED_BT_DEVICE",
"name": "Simulated BT Device",
"groupNames": ["Templates/Roadwork/Devices"],
"tags": [
{ "tag": "class", "value": "roadwork" },
{ "tag": "deviceType", "value": "TrackedDevice" }
],
"items": [
{
"name": "GeoJSON Data",
"type": 2,
"key": "state.current.json_geojson",
"value_type": 4,
"history": "7d",
"description": "Trapper item receiving GeoJSON payloads"
}
]
}
]
}
```

470
docs/queries/sample_push_geojson_history.graphql Normal file
View file

@ -0,0 +1,470 @@
### Mutation
Use this mutation to push multiple GeoJSON data points to a simulated device. Each point is pushed with its own timestamp extracted from the GeoJSON properties.
```graphql
mutation PushGeoJsonHistory($host: String!, $key: String!, $values: [HistoryPushInput!]!) {
pushHistory(host: $host, key: $key, values: $values) {
message
data {
itemid
error {
message
}
}
}
}
```
### Variables
The following variables push 20 GeoJSON features to the `Vehicle1` host.
Note that we use the technical Zabbix key `state.current.json_geojson` (including the `json_` prefix) to target the correct trapper item.
```json
{
"host": "Vehicle1",
"key": "state.current.json_geojson",
"values": [
{
"timestamp": "2026-02-02T16:00:00.000Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:00:00.000Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.980238638943689,
50.94213786322479
]
}
}
},
{
"timestamp": "2026-02-02T16:00:12.838Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:00:12.838Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.979929916761165,
50.9418828739594
]
}
}
},
{
"timestamp": "2026-02-02T16:00:24.413Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:00:24.413Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.97947100540884,
50.9418828739594
]
}
}
},
{
"timestamp": "2026-02-02T16:00:38.910Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:00:38.910Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.978962030999412,
50.94205111445655
]
}
}
},
{
"timestamp": "2026-02-02T16:00:48.218Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:00:48.218Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.97871171571623,
50.94222198308785
]
}
}
},
{
"timestamp": "2026-02-02T16:00:55.942Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:00:55.942Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.978469744275316,
50.9423402763876
]
}
}
},
{
"timestamp": "2026-02-02T16:01:07.048Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:01:07.048Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.978269492048469,
50.94209317448525
]
}
}
},
{
"timestamp": "2026-02-02T16:01:18.399Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:01:18.399Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.97871171571623,
50.94214574946821
]
}
}
},
{
"timestamp": "2026-02-02T16:01:27.785Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:01:27.785Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.9789870625279775,
50.942303474059884
]
}
}
},
{
"timestamp": "2026-02-02T16:01:38.408Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:01:38.408Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.979103876326803,
50.94255846101797
]
}
}
},
{
"timestamp": "2026-02-02T16:01:50.930Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:01:50.930Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.979337503923659,
50.94283447625244
]
}
}
},
{
"timestamp": "2026-02-02T16:01:58.600Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:01:58.600Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.979475177329533,
50.94300534200477
]
}
}
},
{
"timestamp": "2026-02-02T16:02:15.429Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:02:15.429Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.979212346282509,
50.942618921637944
]
}
}
},
{
"timestamp": "2026-02-02T16:02:30.260Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:02:30.260Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.97896620292093,
50.94228244414538
]
}
}
},
{
"timestamp": "2026-02-02T16:02:36.242Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:02:36.242Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.978816013750361,
50.942166779444534
]
}
}
},
{
"timestamp": "2026-02-02T16:02:46.091Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:02:46.091Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.978582386152624,
50.94196962304159
]
}
}
},
{
"timestamp": "2026-02-02T16:02:56.752Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:02:56.752Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.979003750213366,
50.941948592976075
]
}
}
},
{
"timestamp": "2026-02-02T16:03:15.630Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:03:15.630Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.979721320691965,
50.94181452608393
]
}
}
},
{
"timestamp": "2026-02-02T16:03:24.823Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:03:24.823Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.980071762088585,
50.9418776164344
]
}
}
},
{
"timestamp": "2026-02-02T16:03:36.019Z",
"value": {
"type": "Feature",
"properties": {
"time": "2026-02-02T16:03:36.019Z",
"deviceType": "locationTracker",
"parent": {
"type": "vehicle",
"subType": "forklift",
"name": "vehicle1"
}
},
"geometry": {
"type": "Point",
"coordinates": [
6.980234467022115,
50.94213786322479
]
}
}
}
]
}
```

19
docs/queries/sample_tracked_device_query.graphql Normal file
View file

@ -0,0 +1,19 @@
### Query
Retrieve the state of tracked devices.
```graphql
query GetSimulatedState {
allDevices(tag_deviceType: ["TrackedDevice"]) {
name
host
deviceType
... on TrackedDevice {
state {
current {
geojson
}
}
}
}
}
```

4
docs/tests.md
View file

@ -53,6 +53,9 @@ This document outlines the test cases and coverage for the Zabbix GraphQL API.
- **TC-AUTH-04**: Import user rights.
- **TC-AUTH-05**: Import user rights using sample mutation.
### History and Data Pushing
- **TC-HIST-01**: Push history data using `pushHistory` mutation.
### Query Optimization
- **TC-OPT-01**: Verify that GraphQL queries only fetch requested fields from Zabbix (reduced output).
- **TC-OPT-02**: Verify that skippable Zabbix parameters (like selectItems) are omitted if not requested in GraphQL.
@ -91,6 +94,7 @@ The `runAllRegressionTests` mutation (TC-E2E-02) executes the following checks:
- **State sub-properties**: Verifies that requesting device state sub-properties correctly triggers the retrieval of required Zabbix items, even if `items` is not explicitly requested (verifying the indirect dependency logic).
- **Negative Optimization (allDevices)**: Verifies that items are NOT requested from Zabbix if neither `items` nor `state` (or state sub-properties) are requested within the `allDevices` query.
- **allDevices deviceType filter**: Verifies that the `allDevices` query only returns hosts that have a `deviceType` tag, and that the `deviceType` field is populated for all results.
- **pushHistory mutation**: Verifies that the `pushHistory` mutation correctly pushes data to ZABBIX_TRAP items, using either item ID or a combination of host and item key.
## ✅ Test Coverage Checklist

7653
docs/VCR - Technical product information.pdf → docs/use-cases/VCR - Technical product information.pdf
View file

File diff suppressed because it is too large Load diff

2
docs/use-cases/trade-fair-logistics-requirements.md
View file

@ -1,6 +1,6 @@
# 🏗️ Trade Fair Logistics Requirements
This document outlines the requirements for extending the Zabbix GraphQL API to support trade fair logistics, derived from the analysis of the "KI-gestützte Orchestrierung in der Messelogistik" (AI-supported orchestration in trade fair logistics) pilot at Koelnmesse.
This document outlines the requirements for extending the Zabbix GraphQL API to support trade fair logistics, derived from the analysis of the planned "AI-supported orchestration in trade fair logistics" pilot at Koelnmesse.
## 📋 Project Context
The goal is to use the **Virtual Control Room (VCR)** as an orchestration platform to improve punctuality, throughput, and exception handling in trade fair logistics.