AGENTS.md

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 &quot;pattern&quot;                             # 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