Grafana

Grafana is the open-source dashboard and query front end from Grafana Labs. It connects to the stores that hold metrics, logs and traces, and puts them on shared dashboards, in an ad-hoc Explore view and in alert rules, so an operator reads every signal in one UI instead of one UI for each backend. The official docs at grafana.com/docs/grafana own the full configuration reference.

What it is

A single Go server binary that serves a React web app and an HTTP API. It is a query layer: it keeps its own state (users, organizations, teams, dashboards, folders, data source settings, alert rules) in a SQL database and leaves the telemetry where it already lives. Each source is a data source plugin. Prometheus, Loki, Tempo, Elasticsearch, PostgreSQL, MySQL and CloudWatch ship in the core; hundreds more come from the plugin catalog.

The licence is AGPL-3.0 (Grafana Labs relicensed from Apache 2.0 in 2021). Running an unmodified Grafana for internal dashboards has no AGPL obligations beyond the licence text. Modifying it and offering it as a network service to others does. Grafana Enterprise adds features such as team sync from identity-provider groups, reporting and enterprise data source plugins. Grafana Cloud is the hosted service.

The current line is v13.2 (v13.2.4 shipped 2026-10-13, with v13.1.8, v13.0.11 and v12.4.13 patch releases the same day). Grafana 13.0 was a major release with breaking changes; see Gotchas. Grafana belongs to the LGTM family from the same vendor: Loki (logs), Grafana (UI), Tempo (traces), Mimir (long-term metrics), plus Alloy as the collector.

How it works

The server has three jobs. It authenticates the user and resolves a role. It loads dashboard JSON from its database or from provisioned files. It runs each panel's query against the right data source and returns data frames that the browser draws. Data source queries go through the backend, so credentials for Prometheus, Loki or a database stay on the server and never reach the browser.

The database holds only Grafana's own state, so it stays small. Losing it loses dashboards and users, not telemetry. That is why most Kubernetes installs keep dashboards and data sources in Git as provisioning files and treat the database as rebuildable.

Components

Part	Job
HTTP server + frontend	Serves the UI and the /api and /apis endpoints
Auth	Basic login, API tokens, service accounts, OAuth/OIDC, SAML (Enterprise), LDAP, auth proxy
Data source proxy and backend plugins	Run queries against each source and return data frames
Unified alerting	Evaluates alert rules on a schedule and routes notifications through an embedded Alertmanager, or forwards to an external one
Provisioning	Loads data sources, dashboards and alert rules from YAML/JSON files at start-up
SQL database	SQLite file by default; MySQL or PostgreSQL for more than one replica

When to use it

Reach for it when:

• You already run Prometheus, Loki, Tempo or a SQL store and need dashboards on top.
• You want one UI across signals: jump from a metric spike to the logs from that pod, then to a trace.
• You need dashboards as code: provisioned JSON in Git, or Git Sync in Grafana 13.
• You want single sign-on with role mapping from an OIDC provider's groups.

Skip it when:

• You have no telemetry store yet. Grafana stores nothing; pick the store first.
• A managed vendor UI (Datadog, CloudWatch dashboards) already covers the need and nobody wants to run another server.
• The need is business BI over a warehouse with joins and drill-downs. Metabase or Superset fit that better.
• AGPL is not acceptable for a product that embeds and redistributes a modified Grafana.

At a glance

Core concepts

• Data source — a connection to a backend, identified by a stable uid.
• Dashboard — JSON: panels, variables, time range. Stored in the database or provisioned from files.
• Variable — a dropdown ($cluster, $namespace) filled by a query and substituted into every panel.
• Explore — ad-hoc querying without a dashboard. The usual place to read logs and traces.
• Organization / team / role — Viewer, Editor and Admin per org, plus Grafana Admin for the whole server.
• Correlations — derived fields, trace-to-logs and exemplars that link one signal to another.

Key facts (v13.2)

Item	Value
Licence	AGPL-3.0 (OSS); Enterprise and Cloud are commercial
Default port	3000
Default database	SQLite file; MySQL or PostgreSQL for HA
Helm chart	grafana-community/helm-charts (moved from grafana/helm-charts after 2026-01-30)
CLI	grafana server, grafana cli (the old grafana-server and grafana-cli binaries are gone in 13.0)
New API layer	/apis (App Platform); /api is deprecated

Grafana compared

Aspect	Grafana	Kibana	Perses
Data sources	Many: Prometheus, Loki, SQL, cloud, plugins	Elasticsearch only	Prometheus, Tempo, Loki and a growing list
Licence	AGPL-3.0	Elastic licence / SSPL / AGPL options	Apache 2.0
Dashboards as code	Provisioning files, Git Sync, Terraform	Saved objects API	CRDs and a CLI, designed for GitOps
Alerting	Built in	Built in (Elastic alerting)	Not the focus

How to integrate

Install with Helm

helm repo add grafana-community https://grafana-community.github.io/helm-charts
helm repo update
helm install grafana grafana-community/grafana \
  --namespace monitoring --create-namespace -f values.yaml

kube-prometheus-stack pulls the same chart in as a dependency, so in that stack these values sit under a top-level grafana: key.

Keycloak sign-in and data sources

# values.yaml
admin:
  existingSecret: grafana-admin          # break-glass local admin, not in Git
envFromSecret: grafana-oauth             # provides GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET
grafana.ini:
  server:
    root_url: https://grafana.example.com
  auth.generic_oauth:
    enabled: true
    name: Keycloak
    allow_sign_up: true
    client_id: grafana
    scopes: openid email profile offline_access
    auth_url: https://sso.example.com/realms/main/protocol/openid-connect/auth
    token_url: https://sso.example.com/realms/main/protocol/openid-connect/token
    api_url: https://sso.example.com/realms/main/protocol/openid-connect/userinfo
    email_attribute_path: email
    login_attribute_path: preferred_username
    groups_attribute_path: groups
    role_attribute_path: contains(groups[*], 'grafana-admins') && 'Admin' || 'Viewer'
    use_refresh_token: true
datasources:
  datasources.yaml:
    apiVersion: 1
    datasources:
      - name: Prometheus
        uid: prometheus
        type: prometheus
        url: http://prometheus:9090
        isDefault: true
      - name: Loki
        uid: loki
        type: loki
        url: http://loki:3100
        jsonData:
          derivedFields:
            - name: TraceID
              matcherRegex: "traceID=(\\w+)"
              datasourceUid: tempo
              url: '$${__value.raw}'
      - name: Tempo
        uid: tempo
        type: tempo
        url: http://tempo:3200
        jsonData:
          tracesToLogsV2:
            datasourceUid: loki
            filterByTraceID: true
          serviceMap:
            datasourceUid: prometheus

On the Keycloak side: a confidential client with the redirect URI https://grafana.example.com/login/generic_oauth, and a Group Membership mapper with token claim name groups, Full group path off, added to the ID token and userinfo.

Dashboards from ConfigMaps

The chart's dashboard sidecar loads any ConfigMap with the grafana_dashboard label:

sidecar:
  dashboards:
    enabled: true
    label: grafana_dashboard
    searchNamespace: ALL

kubectl -n monitoring create configmap app-dashboard --from-file=app.json
kubectl -n monitoring label configmap app-dashboard grafana_dashboard=1

In the GL stack

Grafana 13.2.4 is the one UI for metrics, logs and traces across the three K3s clusters behind builddaily.io, paiddaily.io and the other products.

• Where it runs. Grafana runs on the management cluster. It is installed by kube-prometheus-stack together with the Prometheus hub and Alertmanager, so all three ship and upgrade as one release.
• Data sources. Three: the Prometheus hub, Loki and Tempo, all on the management cluster. The beta and prod clusters run Prometheus in agent mode and remote-write to the hub, and every series carries a cluster label, so a single Prometheus data source covers all three clusters. Alloy on each cluster pushes pod logs to Loki with the same label.
• Sign-in. Login goes through Keycloak over OIDC. Keycloak runs on the prod cluster and also signs users in to Rancher, Argo CD and kubectl. Members of the Keycloak group grafana-admins get the admin role in Grafana.
• Break-glass. A local Grafana admin account stays enabled, so dashboards stay reachable if Keycloak or the prod cluster is down. This matters because Grafana is one of the tools used to diagnose that outage.

Gotchas

• Grafana 13.0 breaking changes. grafana-server and grafana-cli are removed (use grafana server and grafana cli). The numeric-ID data source APIs are off by default (use uid). The Image Renderer plugin is no longer supported for screenshots and reports. HTTP gzip is now on by default. Check scripts, probes and custom images before upgrading.
• Git Sync early adopters on 12.x. The 13.0 notes warn that dashboards and folders can be lost or reverted when Git Sync users on 12.x upgrade, and that 13.0.1 does not recover them. Back up the database first.
• SQLite and replicas. The default SQLite file cannot be shared between replicas. More than one replica needs MySQL or PostgreSQL. The chart also ships with persistence.enabled: false, so dashboards saved in the UI disappear when the pod restarts unless persistence is on or dashboards are provisioned.
• Secrets in grafana.ini. The chart's assertNoLeakedSecrets check fails the render if a secret such as client_secret appears in plain values. Pass it as an environment variable (GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET) or with $__env{...} / $__file{...} expansion.
• root_url behind a proxy. Without the public root_url, Grafana builds the OAuth callback with the wrong host and Keycloak rejects the redirect URI.
• No groups claim by default. Keycloak does not add groups to tokens until a Group Membership mapper exists. With Full group path on, the claim is /grafana-admins, and a match on grafana-admins fails.
• Silent fallback role. When role_attribute_path matches nothing, the user gets the default Viewer role. Set role_attribute_strict = true to deny login instead.
• $ in provisioning YAML. Provisioning files expand environment variables, so a literal $ (as in ${__value.raw}) must be written $$.
• Provisioned dashboards are read-only in the UI unless the provider sets allowUiUpdates. Edits must go to the source file, or the next sync overwrites them.

Risks

• AGPL-3.0. Fine for internal use. A product that modifies Grafana and serves it to customers must publish those changes. Check with counsel before embedding it.
• Single-vendor stewardship. Grafana Labs sets the roadmap and decides which features stay Enterprise or Cloud only, team sync for example.
• Credential concentration. Grafana stores credentials for every data source. Its admin account, its database and its service-account tokens need the same protection as the stores behind them.
• Fast release cadence. Four patch lines ship together roughly every two weeks, and majors bring breaking changes. Falling behind turns into a multi-version upgrade.

Alternatives

• Perses — CNCF dashboard project, Apache 2.0, dashboards as Kubernetes CRDs. Pick it when GitOps-native dashboards and a permissive licence matter more than plugin breadth.
• Kibana — the Elastic Stack UI. Pick it when the data already lives in Elasticsearch.
• Prometheus UI and Alertmanager UI — built in, zero extra servers. Pick them for ad-hoc PromQL and silences when shared dashboards are not needed.
• Grafana Cloud — the same UI, hosted. Pick it when nobody wants to run the server or its database.

Related

• Prometheus, Loki and Tempo — the three data sources behind every dashboard.
• Alloy and OpenTelemetry — the collectors that feed logs and traces in.
• Alertmanager and Pyrra — alert routing and the SLO rules that Grafana dashboards display.
• Keycloak — the single sign-on in front of Grafana.
• Rancher and K3s — the clusters Grafana watches.
• Official: Grafana docs, What's new in Grafana 13.0, Keycloak OAuth setup, grafana/grafana releases.