Debugging

Practical knobs for figuring out what's wrong in a running Grafana.

Logs

Configuration lives under the [log] section of conf/defaults.ini. Set per-component log levels in custom.ini:

[log]
level = info

[log.console]
level = debug

[log.frontend]
enabled = true

The Go logger is in pkg/infra/log/. Most services obtain a named logger via log.New("dashboards") or log.New("alerting.scheduler"); grep for log.New( to find log namespaces and silence/escalate them in custom.ini under [log.<namespace>].

The frontend logger is wired through pkg/api/frontend_logging.go — browser-side errors and Sentry-style events are POSTed back to the server when frontend_logging is enabled.

Common errors and where they come from

• failed to load plugin: rpc error: code = Unavailable — backend plugin process crashed during init. Look at data/log/grafana.log for the plugin's stderr and check pkg/plugins/manager/.
• dashboard not found from the API — check pkg/services/dashboards/ and ensure the user's RBAC permissions cover the folder; permissions often mask "not found" from a real ACL denial.
• alert rule already exists — the ngalert provisioner has a unique-by-(orgID, namespace, group, title) constraint enforced in pkg/services/ngalert/store/.
• no datasource for queries — Explore/dashboard tried to run a query against an unknown UID. Check the response in the network tab and pkg/services/datasources/.
• WebSocket disconnect loops — pkg/services/live/ requires the same orgID across the connection lifecycle and a working session cookie.

Inspectors

• Dashboard panel inspect (panel kebab → Inspect) shows the raw query, the response data frame, and timing. The "Query" tab is the most useful when chasing a bad render.
• Profile → Stats in the UI shows server stats; the corresponding endpoint is /api/admin/stats from pkg/api/admin.go.
• /api/health and /api/metrics — health check and Prometheus-format metrics. Code in pkg/api/health.go and the metrics middleware in pkg/middleware/.

Tracing

Grafana emits OpenTelemetry traces when configured. The wiring is in pkg/infra/tracing/. Set [tracing.opentelemetry] in your config to a valid endpoint, then recreate the issue.

Database

The default SQLite database is data/grafana.db. You can poke it with sqlite3 while the server is stopped, or start a Postgres/MySQL devenv and inspect those.

For schema reference, all migrations live in pkg/services/sqlstore/migrations/ and run forward-only at startup.

Backend debugger

make run compiles with -gcflags all=-N -l so you can attach Delve (dlv attach <pid>). The PID you want is the child of air, not the air process itself.

Frontend debugger

• Source maps are emitted in dev so Chrome / Firefox debuggers work directly against .ts / .tsx.
• React Devtools and Redux Devtools are both supported — the Redux store is exposed in dev only.
• For Playwright failures, run yarn e2e:playwright:debug to get the inspector + traces.

Support bundles

For end-user troubleshooting, Grafana can produce a "support bundle" — a zip of redacted config, logs, and metadata. The implementation is in pkg/services/supportbundles/ and the UI under public/app/features/support-bundles/.