CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Grafana-Zabbix is a hybrid Grafana plugin connecting Grafana to Zabbix monitoring infrastructure. It consists of three components:

Zabbix App (/src) - Container app plugin
Zabbix Data Source (/src/datasource) - TypeScript frontend + Go backend for querying Zabbix
Problems Panel (/src/panel-triggers) - React panel for displaying Zabbix problems/triggers

Build Commands

# Install all dependencies
make install           # or: yarn install && go install -v ./pkg/

# Development
yarn dev               # Watch mode for frontend
make run-backend       # Watch mode for backend (uses bra)

# Production build
make build             # or: yarn build && mage -v build:backend

# Distribution (all platforms)
make dist

# After building, restart Grafana to reload the plugin
podman container stop grafana && podman container start grafana

Testing

# Frontend tests (Jest)
yarn test              # Watch mode
yarn test:ci           # CI mode, all tests

# Run specific test file
yarn test datasource.test.ts
yarn test Problems.test.tsx

# Backend tests (Go)
go test ./pkg/...

Test files are located alongside source code with .test.ts or .test.tsx extensions:

src/datasource/specs/*.test.ts
src/datasource/components/**/*.test.tsx
src/datasource/zabbix/**/*.test.ts
src/panel-triggers/components/**/*.test.tsx

Linting and Type Checking

yarn lint              # Check for linting errors
yarn lint:fix          # Auto-fix lint and formatting issues
yarn typecheck         # TypeScript type checking

Development Environment

yarn server            # Start Grafana + Zabbix via Docker Compose
yarn server:down       # Stop and remove containers

Docker setup in /devenv/ includes multiple Zabbix versions (5.0, 6.0, 7.0, 7.2, 7.4) for compatibility testing.

Architecture

Frontend-Backend Communication: Frontend queries go through Grafana's backend proxy to the plugin backend executable (gpx_zabbix-datasource), which handles Zabbix API calls. Uses gRPC via Grafana Plugin SDK.

Key Frontend Packages:

/src/datasource/datasource.ts - Main ZabbixDatasource class
/src/datasource/zabbix/ - Zabbix API client logic
/src/datasource/components/ - Query editor, config editor components
/src/panel-triggers/components/ - Problems panel components

Key Backend Packages (/pkg/):

datasource/ - Main backend logic
zabbix/ - Zabbix API interactions
zabbixapi/ - Low-level API connector
cache/ - Caching layer

Requirements

Node.js: v24 (see .nvmrc)
Yarn: v4.12.0
Go: 1.25
Grafana: >=11.6.0

PR Workflow

Run yarn changeset to create a changeset file for your PR. This is required for version bumping and changelog generation.

Debugging Backend

make build-debug       # Build with debug flags
./debug-backend.sh     # Attach delve debugger (after starting Grafana)

VS Code debug config connects to delve on port 3222.

3.1 KiB Raw Blame History