| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 1 | 25 | 0% |
| Commands | 0 | 0 | 38 | 0% |
| Section tags | 1 | 0 | 9 | 10% |
What each file covers
Sections
0 shared · 1 only in A · 25 only in B- − Panels — agent guide
- + AGENTS.md
- + Project Overview
- + Principles
- + Comments
- + Human Review Gates
- + Commands
- + Build & Run
- + Test
- + Backend
- + Frontend
- + E2E
- + Lint & Format
- + Code Generation
- + Dev Environment
- + Architecture
- + Backend (`pkg/`)
- + Frontend (`public/app/`)
- + Shared Packages (`packages/`)
- + Backend Apps (`apps/`)
- + Plugin Workspaces
- + Key Notes
- + Cursor Cloud specific instructions
- + Prerequisites
- + Running services
- + Testing gotchas
Commands
0 shared · 0 only in A · 38 only in B- + make run
- + make build-backend
- + yarn start
- + yarn build
- + go test -run TestName ./pkg/services/myservice/
- + make test-go-unit
- + make test-go-integration
- + yarn test path/to/file
- + yarn test -t "pattern"
- + yarn test -u
- + yarn e2e:playwright path/to/test.spec.ts
- + make lint-go
- + yarn lint
- + yarn lint:fix
- + yarn prettier:write
- + yarn typecheck
- + make gen-go
- + make gen-cue
- + make gen-apps
- + make swagger-gen
- + make gen-feature-toggles
- + make i18n-extract
- + make update-workspace
- + yarn install --immutable
- + make devenv sources=influxdb
- + make devenv-down
- + make lefthook-install
- + git push
- + yarn workspace @grafana-plugins/<name> dev
- + go.work
- + make devenv sources=postgres_tests,mysql_tests
- + make test-go-integration-postgres
- + node
- + yarn
- + jest
- + go.mod
- + yarn test
- + yarn jest --no-watch
Section tags
1 shared · 0 only in A · 9 only in B- + setup
- + build
- + test
- + lint-format
- + architecture
- + testing-strategy
- + git-pr
- + dependencies
- + docs
- agent-behaviour
Line diff
grafana/grafana · public/app/plugins/panel/AGENTS.md
@@ −1 @@
1# Panels — agent guide
2
3Built-in visualization panels live here. When adding or changing panel code — and
4especially its tests — invoke these skills with the Skill tool:
5
6- **`panel-testing-strategy`** — how panel/visualization unit + E2E tests should be
7 written: assert real behavior (not existence), the canvas draw-call snapshot
8 harness, and the anti-flake rules. Read it before writing or reviewing panel tests.
9- **`add-e2e-selectors`** — add versioned `@grafana/e2e-selectors` and wire
10 `data-testid` into JSX when making panel UI testable.
11
grafana/grafana · AGENTS.md
@@ +1 @@
1# AGENTS.md
2
3<!-- version: 2.0.0 -->
4
5This file provides guidance to AI agents when working with code in the Grafana repository.
6
7**Directory-scoped agent files exist for specialized areas — read them when working in those directories:**
8
9- `docs/AGENTS.md` — Documentation style guide (for work under `docs/`)
10- `public/app/features/alerting/unified/AGENTS.md` — Alerting squad patterns
11- `pkg/storage/unified/AGENTS.md` — Unified storage/search compatibility rules (for work under `pkg/storage/unified/`)
12- `public/app/core/journeys/AGENTS.md` — Critical User Journey instrumentation
13
14## Project Overview
15
16Grafana is a monitoring and observability platform. Go backend, TypeScript/React frontend, monorepo with Yarn workspaces (frontend) and Go workspaces (backend).
17
18## Principles
19
20- Follow existing patterns in the surrounding code
21- Write tests for new functionality
22- Keep changes focused — avoid over-engineering
23- Separate PRs for frontend and backend changes (deployed at different cadences)
24- Security: prevent XSS, SQL injection, command injection
25
26## Comments
27
28- Only add a comment when it explains **why** something is done or reveals non-obvious logic that a reader must know to safely change the code. If the code is self-explanatory, no comment is needed.
29- Never include links (Slack, GitHub, Jira, etc.) in code comments.
30
31## Human Review Gates
32
33Before running `git push`, stop and get explicit human approval. When changes are ready, show a summary of changes and wait for instruction. "Open a PR" in a task description is intent, not permission to push without review.
34
35## Commands
36
37### Build & Run
38
39```bash
40make run # Backend with hot reload (localhost:3000, admin/admin)
41make build-backend # Backend only
42yarn start # Frontend dev server (watches for changes)
43yarn build # Frontend production build
44```
45
46### Test
47
48```bash
49# Backend
50go test -run TestName ./pkg/services/myservice/ # Specific test
51make test-go-unit # All unit tests
52make test-go-integration # Integration tests
53
54# Frontend
55yarn test path/to/file # Specific file
56yarn test -t "pattern" # By name pattern
57yarn test -u # Update snapshots
58
59# E2E
60yarn e2e:playwright path/to/test.spec.ts # Specific test
61```
62
63### Lint & Format
64
65```bash
66make lint-go # Go linter
67yarn lint # ESLint
68yarn lint:fix # ESLint auto-fix
69yarn prettier:write # Prettier auto-format
70yarn typecheck # TypeScript check
71```
72
73### Code Generation
74
75```bash
76make gen-go # Wire DI (after changing service init)
77make gen-cue # CUE schemas (after changing kinds/)
78make gen-apps # App SDK apps
79make swagger-gen # OpenAPI/Swagger specs
80make gen-feature-toggles # Feature flags (pkg/services/featuremgmt/)
81make i18n-extract # i18n strings
82make update-workspace # Go workspace (after adding modules)
83```
84
85### Dev Environment
86
87```bash
88yarn install --immutable # Install frontend deps
89make devenv sources=influxdb # Start backing services
90make devenv-down # Stop backing services
91make lefthook-install # Pre-commit hooks
92```
93
94## Architecture
95
96### Backend (`pkg/`)
97
98| Directory | Purpose |
99| ----------------- | ----------------------------------------------------------- |
100| `pkg/api/` | HTTP API handlers and routes |
101| `pkg/services/` | Business logic by domain (alerting, dashboards, auth, etc.) |
102| `pkg/server/` | Server init and Wire DI setup (`wire.go`) |
103| `pkg/tsdb/` | Time series database query backends |
104| `pkg/plugins/` | Plugin system and loader |
105| `pkg/infra/` | Logging, metrics, database access |
106| `pkg/middleware/` | HTTP middleware |
107| `pkg/setting/` | Configuration management |
108
109**Patterns**: Wire DI (regenerate with `make gen-go`), services implement interfaces in same package, business logic in `pkg/services/<domain>/` not in API handlers, database via `sqlstore`, plugin communication via gRPC/protobuf.
110
111### Frontend (`public/app/`)
112
113| Directory | Purpose |
114| ---------------------- | ----------------------------------------------------- |
115| `public/app/core/` | Shared services, components, utilities |
116| `public/app/features/` | Feature code by domain (dashboard, alerting, explore) |
117| `public/app/plugins/` | Built-in plugins (many are Yarn workspaces) |
118| `public/app/types/` | TypeScript type definitions |
119| `public/app/store/` | Redux store configuration |
120
121**Patterns**: Redux Toolkit with slices (not old Redux), function components with hooks, Emotion CSS-in-JS via `useStyles2`, RTK Query for data fetching, React Testing Library for tests.
122
123### Shared Packages (`packages/`)
124
125`@grafana/data` (data structures), `@grafana/ui` (components), `@grafana/runtime` (runtime services), `@grafana/schema` (CUE-generated types), `@grafana/scenes` (dashboard framework).
126
127### Backend Apps (`apps/`)
128
129Standalone Go apps using Grafana App SDK: `apps/dashboard/`, `apps/folder/`, `apps/alerting/`.
130
131### Plugin Workspaces
132
133These built-in plugins require separate build steps: `azuremonitor`, `loki`, `grafana-testdata-datasource`.
134
135Build a specific plugin: `yarn workspace @grafana-plugins/<name> dev`
136
137## Key Notes
138
139- **Wire DI**: Backend service init changes require `make gen-go`. Wire catches circular deps at compile time.
140- **CUE schemas**: Dashboard/panel schemas in `kinds/` generate both Go and TS code via `make gen-cue`.
141- **Feature toggles**: Defined in `pkg/services/featuremgmt/`, auto-generate code. Run `make gen-feature-toggles` after changes.
142- **Go workspace**: Defined in `go.work`. Run `make update-workspace` when adding Go modules.
143- **Build tags**: `oss` (default), `enterprise`, `pro`.
144- **Config**: Defaults in `conf/defaults.ini`, overrides in `conf/custom.ini`.
145- **Database migrations**: Live in `pkg/services/sqlstore/migrations/`. Test with `make devenv sources=postgres_tests,mysql_tests` then `make test-go-integration-postgres`.
146- **CI sharding**: Backend tests use `SHARD`/`SHARDS` env vars for parallelization.
147- **Service compatibility**: Unified storage/search (`pkg/storage/unified/`) can be deployed as separate services at a different cadence than the Grafana API layer. Changes spanning API-layer callers and `pkg/storage/unified/` must be backwards compatible in both directions — see `pkg/storage/unified/AGENTS.md`.
148
149## Cursor Cloud specific instructions
150
151### Prerequisites
152
153- **Node.js** — version pinned in `.nvmrc` (check that file for the exact version). Installed via nvm and set as the nvm default. **PATH gotcha:** the infra injects `/exec-daemon/node` ahead of nvm, so the plain non-login shell may resolve `node` to an older version — check it satisfies the `engines` range in `package.json` (it does today, so builds/tests work), but it is not the pinned version. Login shells (tmux sessions, `bash -lc '...'`) get the pinned version because `~/.bashrc` prepends the nvm bin. Run `yarn` / `yarn start` / `jest` / webpack via a login shell (tmux or `bash -lc`) to use the pinned Node.
154- **Go** — version pinned in `go.mod` (check that file for the exact version), installed at `/usr/local/go` and symlinked to `/usr/local/bin/go`. The distro `/usr/bin/go` is older; `/usr/local/bin` wins in PATH so `go` resolves correctly. If `go.mod` bumps Go, reinstall a matching toolchain into `/usr/local/go`.
155- **Yarn** via corepack — version pinned by `package.json` `packageManager` (check that field for the exact version). Run `corepack enable` if `yarn` is not found. `.yarnrc.yml` sets `enableScripts: false`, so dependency build/lifecycle scripts are disabled by default.
156- **GCC** required for CGo/SQLite compilation of the backend.
157- Repos in this environment live under `/agent/repos/<repo>` (e.g. `/agent/repos/grafana`); this is a multi-repo workspace, not the single `~/grafana` layout described in `grafana-enterprise/AGENTS.md`.
158
159### Running services
160
161- **Backend**: `make run` — builds and starts Grafana backend with hot-reload (air) on `localhost:3000`. Default login: `admin`/`admin`. First build takes ~3 minutes due to debug symbols (`-gcflags all=-N -l`); subsequent hot-reload rebuilds are faster.
162- **Frontend**: `yarn start` — starts webpack dev server that watches for changes. The backend proxies to it. First compile takes ~45s.
163- No external databases required — Grafana uses embedded SQLite by default.
164
165### Testing gotchas
166
167- **Frontend tests**: The `yarn test` script includes `--watch` by default. Always use `yarn jest --no-watch` or add `--watchAll=false` to run tests once and exit.
168- **Backend tests**: Some packages (e.g. `pkg/api/`) have slow test compilation (~2 min) due to large dependency graphs. Use targeted test runs with `-run TestName` where possible.
169- All standard build/test/lint commands are documented in the Commands section above.
170
@@ −1 +1 @@
1−# Panels — agent guide
1+# AGENTS.md
22
3−Built-in visualization panels live here. When adding or changing panel code — and
4−especially its tests — invoke these skills with the Skill tool:
3+<!-- version: 2.0.0 -->
54
6−- **`panel-testing-strategy`** — how panel/visualization unit + E2E tests should be
7− written: assert real behavior (not existence), the canvas draw-call snapshot
8− harness, and the anti-flake rules. Read it before writing or reviewing panel tests.
9−- **`add-e2e-selectors`** — add versioned `@grafana/e2e-selectors` and wire
10− `data-testid` into JSX when making panel UI testable.
5+This file provides guidance to AI agents when working with code in the Grafana repository.
6+
7+**Directory-scoped agent files exist for specialized areas — read them when working in those directories:**
8+
9+- `docs/AGENTS.md` — Documentation style guide (for work under `docs/`)
10+- `public/app/features/alerting/unified/AGENTS.md` — Alerting squad patterns
11+- `pkg/storage/unified/AGENTS.md` — Unified storage/search compatibility rules (for work under `pkg/storage/unified/`)
12+- `public/app/core/journeys/AGENTS.md` — Critical User Journey instrumentation
13+
14+## Project Overview
15+
16+Grafana is a monitoring and observability platform. Go backend, TypeScript/React frontend, monorepo with Yarn workspaces (frontend) and Go workspaces (backend).
17+
18+## Principles
19+
20+- Follow existing patterns in the surrounding code
21+- Write tests for new functionality
22+- Keep changes focused — avoid over-engineering
23+- Separate PRs for frontend and backend changes (deployed at different cadences)
24+- Security: prevent XSS, SQL injection, command injection
25+
26+## Comments
27+
28+- Only add a comment when it explains **why** something is done or reveals non-obvious logic that a reader must know to safely change the code. If the code is self-explanatory, no comment is needed.
29+- Never include links (Slack, GitHub, Jira, etc.) in code comments.
30+
31+## Human Review Gates
32+
33+Before running `git push`, stop and get explicit human approval. When changes are ready, show a summary of changes and wait for instruction. "Open a PR" in a task description is intent, not permission to push without review.
34+
35+## Commands
36+
37+### Build & Run
38+
39+```bash
40+make run # Backend with hot reload (localhost:3000, admin/admin)
41+make build-backend # Backend only
42+yarn start # Frontend dev server (watches for changes)
43+yarn build # Frontend production build
44+```
45+
46+### Test
47+
48+```bash
49+# Backend
50+go test -run TestName ./pkg/services/myservice/ # Specific test
51+make test-go-unit # All unit tests
52+make test-go-integration # Integration tests
53+
54+# Frontend
55+yarn test path/to/file # Specific file
56+yarn test -t "pattern" # By name pattern
57+yarn test -u # Update snapshots
58+
59+# E2E
60+yarn e2e:playwright path/to/test.spec.ts # Specific test
61+```
62+
63+### Lint & Format
64+
65+```bash
66+make lint-go # Go linter
67+yarn lint # ESLint
68+yarn lint:fix # ESLint auto-fix
69+yarn prettier:write # Prettier auto-format
70+yarn typecheck # TypeScript check
71+```
72+
73+### Code Generation
74+
75+```bash
76+make gen-go # Wire DI (after changing service init)
77+make gen-cue # CUE schemas (after changing kinds/)
78+make gen-apps # App SDK apps
79+make swagger-gen # OpenAPI/Swagger specs
80+make gen-feature-toggles # Feature flags (pkg/services/featuremgmt/)
81+make i18n-extract # i18n strings
82+make update-workspace # Go workspace (after adding modules)
83+```
84+
85+### Dev Environment
86+
87+```bash
88+yarn install --immutable # Install frontend deps
89+make devenv sources=influxdb # Start backing services
90+make devenv-down # Stop backing services
91+make lefthook-install # Pre-commit hooks
92+```
93+
94+## Architecture
95+
96+### Backend (`pkg/`)
97+
98+| Directory | Purpose |
99+| ----------------- | ----------------------------------------------------------- |
100+| `pkg/api/` | HTTP API handlers and routes |
101+| `pkg/services/` | Business logic by domain (alerting, dashboards, auth, etc.) |
102+| `pkg/server/` | Server init and Wire DI setup (`wire.go`) |
103+| `pkg/tsdb/` | Time series database query backends |
104+| `pkg/plugins/` | Plugin system and loader |
105+| `pkg/infra/` | Logging, metrics, database access |
106+| `pkg/middleware/` | HTTP middleware |
107+| `pkg/setting/` | Configuration management |
108+
109+**Patterns**: Wire DI (regenerate with `make gen-go`), services implement interfaces in same package, business logic in `pkg/services/<domain>/` not in API handlers, database via `sqlstore`, plugin communication via gRPC/protobuf.
110+
111+### Frontend (`public/app/`)
112+
113+| Directory | Purpose |
114+| ---------------------- | ----------------------------------------------------- |
115+| `public/app/core/` | Shared services, components, utilities |
116+| `public/app/features/` | Feature code by domain (dashboard, alerting, explore) |
117+| `public/app/plugins/` | Built-in plugins (many are Yarn workspaces) |
118+| `public/app/types/` | TypeScript type definitions |
119+| `public/app/store/` | Redux store configuration |
120+
121+**Patterns**: Redux Toolkit with slices (not old Redux), function components with hooks, Emotion CSS-in-JS via `useStyles2`, RTK Query for data fetching, React Testing Library for tests.
122+
123+### Shared Packages (`packages/`)
124+
125+`@grafana/data` (data structures), `@grafana/ui` (components), `@grafana/runtime` (runtime services), `@grafana/schema` (CUE-generated types), `@grafana/scenes` (dashboard framework).
126+
127+### Backend Apps (`apps/`)
128+
129+Standalone Go apps using Grafana App SDK: `apps/dashboard/`, `apps/folder/`, `apps/alerting/`.
130+
131+### Plugin Workspaces
132+
133+These built-in plugins require separate build steps: `azuremonitor`, `loki`, `grafana-testdata-datasource`.
134+
135+Build a specific plugin: `yarn workspace @grafana-plugins/<name> dev`
136+
137+## Key Notes
138+
139+- **Wire DI**: Backend service init changes require `make gen-go`. Wire catches circular deps at compile time.
140+- **CUE schemas**: Dashboard/panel schemas in `kinds/` generate both Go and TS code via `make gen-cue`.
141+- **Feature toggles**: Defined in `pkg/services/featuremgmt/`, auto-generate code. Run `make gen-feature-toggles` after changes.
142+- **Go workspace**: Defined in `go.work`. Run `make update-workspace` when adding Go modules.
143+- **Build tags**: `oss` (default), `enterprise`, `pro`.
144+- **Config**: Defaults in `conf/defaults.ini`, overrides in `conf/custom.ini`.
145+- **Database migrations**: Live in `pkg/services/sqlstore/migrations/`. Test with `make devenv sources=postgres_tests,mysql_tests` then `make test-go-integration-postgres`.
146+- **CI sharding**: Backend tests use `SHARD`/`SHARDS` env vars for parallelization.
147+- **Service compatibility**: Unified storage/search (`pkg/storage/unified/`) can be deployed as separate services at a different cadence than the Grafana API layer. Changes spanning API-layer callers and `pkg/storage/unified/` must be backwards compatible in both directions — see `pkg/storage/unified/AGENTS.md`.
148+
149+## Cursor Cloud specific instructions
150+
151+### Prerequisites
152+
153+- **Node.js** — version pinned in `.nvmrc` (check that file for the exact version). Installed via nvm and set as the nvm default. **PATH gotcha:** the infra injects `/exec-daemon/node` ahead of nvm, so the plain non-login shell may resolve `node` to an older version — check it satisfies the `engines` range in `package.json` (it does today, so builds/tests work), but it is not the pinned version. Login shells (tmux sessions, `bash -lc '...'`) get the pinned version because `~/.bashrc` prepends the nvm bin. Run `yarn` / `yarn start` / `jest` / webpack via a login shell (tmux or `bash -lc`) to use the pinned Node.
154+- **Go** — version pinned in `go.mod` (check that file for the exact version), installed at `/usr/local/go` and symlinked to `/usr/local/bin/go`. The distro `/usr/bin/go` is older; `/usr/local/bin` wins in PATH so `go` resolves correctly. If `go.mod` bumps Go, reinstall a matching toolchain into `/usr/local/go`.
155+- **Yarn** via corepack — version pinned by `package.json` `packageManager` (check that field for the exact version). Run `corepack enable` if `yarn` is not found. `.yarnrc.yml` sets `enableScripts: false`, so dependency build/lifecycle scripts are disabled by default.
156+- **GCC** required for CGo/SQLite compilation of the backend.
157+- Repos in this environment live under `/agent/repos/<repo>` (e.g. `/agent/repos/grafana`); this is a multi-repo workspace, not the single `~/grafana` layout described in `grafana-enterprise/AGENTS.md`.
158+
159+### Running services
160+
161+- **Backend**: `make run` — builds and starts Grafana backend with hot-reload (air) on `localhost:3000`. Default login: `admin`/`admin`. First build takes ~3 minutes due to debug symbols (`-gcflags all=-N -l`); subsequent hot-reload rebuilds are faster.
162+- **Frontend**: `yarn start` — starts webpack dev server that watches for changes. The backend proxies to it. First compile takes ~45s.
163+- No external databases required — Grafana uses embedded SQLite by default.
164+
165+### Testing gotchas
166+
167+- **Frontend tests**: The `yarn test` script includes `--watch` by default. Always use `yarn jest --no-watch` or add `--watchAll=false` to run tests once and exit.
168+- **Backend tests**: Some packages (e.g. `pkg/api/`) have slow test compilation (~2 min) due to large dependency graphs. Use targeted test runs with `-run TestName` where possible.
169+- All standard build/test/lint commands are documented in the Commands section above.
11170
