105 lines
3.1 KiB
Markdown
105 lines
3.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
yarn lint # Check for linting errors
|
|
yarn lint:fix # Auto-fix lint and formatting issues
|
|
yarn typecheck # TypeScript type checking
|
|
```
|
|
|
|
## Development Environment
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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.
|