AGENTS.md
Rama main · réplica de lectura del repositorio original.
# AGENTS.md
<!-- version: 2.0.0 -->
This file provides guidance to AI agents when working with code in the Grafana repository.
**Directory-scoped agent files exist for specialized areas — read them when working in those directories:**
- `docs/AGENTS.md` — Documentation style guide (for work under `docs/`)
- `public/app/features/alerting/unified/AGENTS.md` — Alerting squad patterns
- `pkg/storage/unified/AGENTS.md` — Unified storage/search compatibility rules (for work under `pkg/storage/unified/`)
- `public/app/core/journeys/AGENTS.md` — Critical User Journey instrumentation
## Project Overview
Grafana is a monitoring and observability platform. Go backend, TypeScript/React frontend, monorepo with pnpm workspaces (frontend) and Go workspaces (backend).
## Principles
- Follow existing patterns in the surrounding code
- Write tests for new functionality — for Go code, use `testing/synctest` over sleeps and
time-based assertions; for frontend code, use the `frontend-testing-strategy` skill for this
repo's testing conventions (and `panel-testing-strategy` on top of it for visualization/panel code)
- Keep changes focused — avoid over-engineering
- Separate PRs for frontend and backend changes (deployed at different cadences)
- Security: prevent XSS, SQL injection, command injection
- Security issues should be reported via [Grafana's security issue reporting page](https://grafana.com/legal/report-a-security-issue/) and not directly in this repository.
## Code Review Rules
### Metrics
- Review metric changes against `contribute/backend/instrumentation.md`, especially registration, duplicate registration, label cardinality, and the impact of renames on dashboards and alerts.
## Comments
- 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.
- Never include links (Slack, GitHub, Jira, etc.) in code comments.
## Human Review Gates
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.
## Commands
### Build & Run
```bash
make run # Backend with hot reload (localhost:3000, admin/admin)
make build-backend # Backend only
pnpm start # Frontend dev server (watches for changes)
pnpm build # Frontend production build
```
### Test
```bash
# Backend
go test -run TestName ./pkg/services/myservice/ # Specific test
make test-go-unit # All unit tests
make test-go-integration # Integration tests
# Frontend
pnpm test path/to/file # Specific file
pnpm test -t "pattern" # By name pattern
pnpm test -u # Update snapshots
# E2E
pnpm e2e:playwright path/to/test.spec.ts # Specific test
```
### Lint & Format
```bash
make lint-go # Go linter
pnpm lint # ESLint
pnpm lint:fix # ESLint auto-fix
pnpm prettier:write # Prettier auto-format
pnpm typecheck # TypeScript check
```
### Code Generation
```bash
make gen-go # Wire DI (after changing service init)
make gen-cue # CUE schemas (after changing kinds/)
make gen-apps # App SDK apps
make swagger-gen # OpenAPI/Swagger specs
make gen-feature-toggles # Feature flags (pkg/services/featuremgmt/)
make i18n-extract # i18n strings
make update-workspace # Go workspace (after adding modules)
```
### Dev Environment
```bash
pnpm install --frozen-lockfile # Install frontend deps
make devenv sources=influxdb # Start backing services
make devenv-down # Stop backing services
make lefthook-install # Pre-commit hooks
```
## Architecture
### Backend (`pkg/`)
| Directory | Purpose |
| ----------------- | ----------------------------------------------------------- |
| `pkg/api/` | HTTP API handlers and routes |
| `pkg/services/` | Business logic by domain (alerting, dashboards, auth, etc.) |
| `pkg/server/` | Server init and Wire DI setup (`wire.go`) |
| `pkg/tsdb/` | Time series database query backends |
| `pkg/plugins/` | Plugin system and loader |
| `pkg/infra/` | Logging, metrics, database access |
| `pkg/middleware/` | HTTP middleware |
| `pkg/setting/` | Configuration management |
**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.
### Frontend (`public/app/`)
| Directory | Purpose |
| ---------------------- | ----------------------------------------------------- |
| `public/app/core/` | Shared services, components, utilities |
| `public/app/features/` | Feature code by domain (dashboard, alerting, explore) |
| `public/app/plugins/` | Built-in plugins (many are pnpm workspaces) |
| `public/app/types/` | TypeScript type definitions |
| `public/app/store/` | Redux store configuration |
**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.
### Shared Packages (`packages/`)
`@grafana/data` (data structures), `@grafana/ui` (components), `@grafana/runtime` (runtime services), `@grafana/schema` (CUE-generated types), `@grafana/scenes` (dashboard framework).
### Backend Apps (`apps/`)
Standalone Go apps using Grafana App SDK: `apps/dashboard/`, `apps/folder/`, `apps/alerting/`.
### Plugin Workspaces
These built-in plugins require separate build steps: `graphite` and `grafana-testdata-datasource`.
Build a specific plugin: `pnpm --filter @grafana-plugins/<name> dev`
## Key Notes
- For unary unified storage gRPC calls, handle the returned error using the guidance in `pkg/storage/unified/resource/doc.go`; failures are reported through gRPC status, not the response's legacy `Error` field. Migrated direct Go calls are also error-only; streaming calls must check terminal errors. The Bulk migration client intentionally retains its legacy response-error fallback until the remote Bulk status rollout is confirmed; see the same guidance.
- **Wire DI**: Backend service init changes require `make gen-go`. Wire catches circular deps at compile time.
- **CUE schemas**: Dashboard/panel schemas in `kinds/` generate both Go and TS code via `make gen-cue`.
- **Feature toggles**: Defined in `pkg/services/featuremgmt/`, auto-generate code. Run `make gen-feature-toggles` after changes.
- **Go workspace**: Defined in `go.work`. Run `make update-workspace` when adding Go modules.
- **Build tags**: `oss` (default), `enterprise`, `pro`.
- **Config**: Defaults in `conf/defaults.ini`, overrides in `conf/custom.ini`.
- **Database migrations**: Live in `pkg/services/sqlstore/migrations/`. Test with `make devenv sources=postgres_tests,mysql_tests` then `make test-go-integration-postgres`.
- **CI sharding**: Backend tests use `SHARD`/`SHARDS` env vars for parallelization.
- **Backend test classification**: Use `TestIntegration*` for tests that need the SQL database matrix. SQLite-only tests and SQL-independent tests should run once in the normal suite. Follow the [backend testing guidelines](contribute/backend/style-guide.md#integration-tests) for short-mode guards, mixed-backend suites, and external-service tests.
- **Metrics**: Before adding, renaming or registering metrics, read `contribute/backend/instrumentation.md` for naming and registration conventions.
- **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`.
## Cursor Cloud specific instructions
### Prerequisites
- **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 `pnpm` / `pnpm start` / `jest` / rspack via a login shell (tmux or `bash -lc`) to use the pinned Node.
- **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`.
- **GCC** required for CGo/SQLite compilation of the backend.
- 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`.
### Running services
- **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.
- **Frontend**: `pnpm start` — starts the rspack dev server, which hot-reloads changes. The backend points the browser at it for frontend assets.
- No external databases required — Grafana uses embedded SQLite by default.
### Testing gotchas
- **Frontend tests**: The `pnpm test` script includes `--watch` by default. Always use `pnpm exec jest --no-watch` or add `--watchAll=false` to run tests once and exit.
- **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.
- All standard build/test/lint commands are documented in the Commands section above.