Generated banner for Grafana Oss
Generated logo for Grafana Oss

Grafana Oss

Grafana LabsOfficialPublished by Grafana Labs

  • Skill
  • Tool integration
  • Cloud and DevOps
  • Apache-2.0
  • Medium risk

From the author

Configure Grafana OSS — provisions dashboards from YAML, sets up data sources (Prometheus / Loki / Tempo / Pyroscope), writes dashboard JSON with template variables, builds panel queries, assigns built-in roles (Viewer / Editor / Admin / GrafanaAdmin), mints service-account tokens, edits grafana.ini server config, creates annotations, installs plugins via provisioning, and validates each step with a health-check curl. Use when building dashboards, configuring data sources, setting up provisioning YAML, picking a panel type, writing template variables, managing users and roles, configuring SMTP/OAuth in grafana.ini, creating annotations via API, troubleshooting why a provisioned dashboard isn't showing up, or running Grafana OSS locally — even when the user says "set up a Prometheus data source", "provision dashboards from git", "make a service account", or "configure SSO in OSS" without saying "Grafana OSS".
— the description by Grafana Labs

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides comprehensive guidance for managing Grafana OSS instances. It covers the full lifecycle of configuration, from setting up data sources like Prometheus, Loki, and Tempo to automating dashboard provisioning via YAML files. It also details user and service account management, RBAC role assignments, plugin installation, and server-level configuration via grafana.ini. The skill emphasizes validation through health-check API calls to ensure that provisioned resources are correctly integrated and operational.

What it does

  • Provisions dashboards and data sources using YAML configuration files.
  • Manages service accounts and mints authentication tokens for API access.
  • Configures server settings, including SMTP and OAuth, via grafana.ini.
  • Assigns built-in roles such as Viewer, Editor, Admin, and GrafanaAdmin.
  • Installs and configures plugins through provisioning workflows.
  • Validates configuration success using API-based health checks.

When to use it

  • When setting up a new Grafana OSS instance or automating environment configuration.
  • When you need to provision dashboards or data sources as code.
  • When managing user access, roles, or service account tokens.
  • When troubleshooting why a provisioned dashboard or data source is not appearing.
  • When configuring server-level settings like authentication or SMTP.

Advantages

  • Enables infrastructure-as-code practices for Grafana configuration.
  • Provides clear, repeatable steps for common administrative tasks.
  • Includes built-in verification steps to confirm configuration success.
  • Centralizes documentation for API interactions and YAML schemas.

Usage examples

“How do I set up a Prometheus data source using a YAML file?”
The agent provides the specific YAML structure for a Prometheus data source, including the required fields like name, type, and URL, and explains how to verify it via the health-check API.
“Create a service account for CI/CD with read-only access.”
The agent provides the YAML configuration for the service account with the 'Viewer' role and the subsequent API commands to mint a token for that account.
“My provisioned dashboard isn't showing up in Grafana. How do I debug it?”
The agent guides you through checking the provisioning logs, verifying the file path, and using the API to confirm if the dashboard UID exists in the system.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/grafana/grafana-oss/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip grafana-oss.zip -d .agents/skills

Documentation by Grafana Labs

Grafana OSS

Docs: https://grafana.com/docs/grafana/latest.md

Common Workflows

Provisioning dashboards from disk
  1. Drop dashboard JSON file(s) under /var/lib/grafana/dashboards/

  2. Add a provider in provisioning/dashboards/default.yaml (see § Dashboard provisioning below)

  3. Restart Grafana so the provider config is loaded

  4. Verify the dashboard landed:

    curl https://grafana.example.com/api/dashboards/uid/<uid> \
      -H "Authorization: Bearer <token>" | jq '.dashboard.title'

    Returns the title → success. 404 → provisioning didn't pick it up; check Grafana server logs (journalctl -u grafana-server | grep -i provisioning) for parse errors.

Provisioning data sources
  1. Write provisioning/datasources/datasources.yaml (see § Data source provisioning below)

  2. Restart Grafana

  3. Health-check the data source via API:

    curl https://grafana.example.com/api/datasources/uid/<uid>/health \
      -H "Authorization: Bearer <token>"
    # { "status": "OK", "message": "..." } → working
    # { "status": "ERROR", ... } → URL unreachable or auth misconfigured
Creating a service account + token
  1. Provision via YAML or POST /api/serviceaccounts (full API in references/api.md § Users + service accounts)

  2. Mint a token via POST /api/serviceaccounts/{id}/tokens

  3. Verify the token works:

    curl https://grafana.example.com/api/org \
      -H "Authorization: Bearer <new-token>"
    # 200 + org JSON → token + role assignment work
    # 401 → token wrong; 403 → role wrong

Dashboard provisioning

# provisioning/dashboards/default.yaml
apiVersion: 1
providers:
  - name: default
    folder: MyFolder
    type: file
    disableDeletion: false
    updateIntervalSeconds: 30
    options:
      path: /var/lib/grafana/dashboards
      foldersFromFilesStructure: true

For the dashboard JSON shape itself (panels, queries, template variables), see references/dashboard-json.md.

Data source provisioning

# provisioning/datasources/datasources.yaml
apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    jsonData:
      timeInterval: 15s
      httpMethod: POST

  - name: Loki
    type: loki
    access: proxy
    url: http://loki:3100

  - name: Tempo
    type: tempo
    access: proxy
    url: http://tempo:3200
    jsonData:
      tracesToLogsV2:
        datasourceUid: loki_uid
        tags: [{ key: "service.name", value: "app" }]
      serviceMap:
        datasourceUid: prometheus_uid
      nodeGraph:
        enabled: true

  - name: Pyroscope
    type: grafana-pyroscope-datasource
    url: http://pyroscope:4040

RBAC (built-in roles)

RolePermissions
ViewerRead dashboards, alerts
EditorCreate/edit dashboards, alerts
AdminManage data sources, users, plugins
GrafanaAdminServer-wide admin (superuser)

Service-account provisioning:

# provisioning/access-control/service_accounts.yaml
apiVersion: 1
serviceAccounts:
  - name: ci-reader
    orgId: 1
    role: Viewer
    tokens:
      - name: ci-token
        # expires: optional ISO 8601 timestamp; omit for no-expiry tokens

(Custom RBAC roles with fine-grained permissions are Enterprise / Cloud only — see the grafana-cloud/admin skill if you need those.)

Plugin provisioning

# provisioning/plugins/plugins.yaml
apiVersion: 1
apps:
  - type: grafana-pyroscope-app
    disabled: false
    jsonData:
      backendUrl: http://pyroscope:4040

After restart, verify via GET /api/plugins/<plugin-id>/health.

References

  • references/dashboard-json.md — full dashboard JSON model + template variables + common problems (uid uniqueness, gridPos arithmetic, datasource uid matching)

  • references/dashboards.md — dashboard workflows, settings, variables, annotations, sharing, versions, playlists, and provisioning-as-code

  • references/datasources.md — data source setup and query examples for Prometheus, Loki, Tempo, SQL, CloudWatch, and plugins

  • references/panel-types.md — panel-type table + decision guide for picking the right one

  • references/panels.md — panel editor, visualization options, field config, transformations, query options, inspection, and performance tips

  • references/alerting.md — alerting concepts, contact points, notification policies, templates, silences, and common rule examples

  • references/api.md — full Grafana OSS API reference (dashboards, data sources, users, service accounts, annotations) with verification curls and common failure modes

  • references/config.md — grafana.ini server / database / SMTP / auth / security / feature-toggle config + restart-required issues

Files

references/datasources.md

Grafana Data Sources - Detailed Reference

Overview

Data sources are connections between Grafana and the systems storing your data. Grafana ships with built-in support for many popular data sources and supports additional sources via plugins.

  • Only Organization Admins can add or remove data sources

  • Each data source has its own query editor

  • Data sources can be used in: Dashboard panels, Explore, Alert rules, Annotations


Managing Data Sources

Add a data source
  1. Go to Connections > Data sources (or Configuration > Data sources in older versions)

  2. Click Add new data source

  3. Search for and select the data source type

  4. Fill in connection details (URL, credentials, etc.)

  5. Click Save & Test to verify the connection

Data source settings (common to all types)
SettingDescription
NameDisplay name used in dashboards
DefaultIf checked, pre-selected in new panels
HTTP URLThe endpoint for the data source server
AuthBasic auth, TLS, bearer token, API key options

Prometheus

Native support - no plugin required.

Configuration
URL: http://prometheus:9090
HTTP method: POST (recommended, supports longer queries)
Key options
OptionDescription
Scrape intervalDefault: 15s - should match your Prometheus scrape interval
Query timeoutDefault: 60s
ExemplarsEnable to link metrics to traces
Ruler URLFor Prometheus-managed alert rules
Query editor
  • Metrics browser: Browse available metrics with autocomplete

  • Query type: Range query (time series) or Instant query (single value)

  • Legend: Customize series labels using {{label_name}} syntax

Template variables with Prometheus
# Variable type: Query
# Query examples:
label_values(metric_name, label_name)    # All values of a label for a metric
label_values(label_name)                  # All values across all metrics
metrics(prefix)                           # All metric names matching prefix
query_result(promql_expression)           # PromQL result as variable values
Exemplars

When enabled, Prometheus exemplars link high-cardinality trace IDs to metric data points. Requires a Tempo data source for trace drill-through.


Loki (Log Aggregation)

Configuration
URL: http://loki:3100
Maximum lines: 1000
Derived fields

Extract values from log lines and link to other systems.

Example - extract trace ID and link to Tempo:

Name: TraceID
Regex: traceID=(\w+)
URL: (internal link to Tempo data source)
Query editor (LogQL)
# Basic log stream selector
{job="nginx", namespace="production"}

# Filter by text
{job="nginx"} |= "error"
{job="nginx"} != "debug"

# Regex filter
{job="nginx"} |~ "status=5\d\d"

# Parse and filter structured logs
{job="api"} | json | level="error"
{job="api"} | logfmt | duration > 1s

# Metrics from logs
rate({job="nginx"} |= "error" [5m])
sum(rate({job="nginx"}[5m])) by (status_code)
Template variables with Loki
label_names()                          # All label names
label_values(label_name)               # All values for a label
label_values({job="nginx"}, pod)       # Label values filtered by stream selector

Tempo (Distributed Tracing)

Configuration
URL: http://tempo:3200
Key options
OptionDescription
Trace to logsLink traces to Loki logs via trace ID
Trace to metricsLink trace spans to Prometheus metrics
Service graphEnable service dependency graph
Node graphShow trace as node graph
TraceQL (query language)
# Find traces with error spans
{status=error}

# Filter by service and duration
{.service.name="frontend" && duration > 1s}

# Structural queries
{.http.url=~"/api/.*"} >> {status=error}

Alertmanager

For connecting to an external Alertmanager.

URL: http://alertmanager:9093
# Implementation: Prometheus, Mimir, or Cortex

Elasticsearch / OpenSearch

Configuration
URL: http://elasticsearch:9200
Index name: logs-*
Time field name: @timestamp
Elasticsearch version: 8.x

MySQL

Built-in support for MySQL 5.7+ and compatible databases (MariaDB, Percona, Amazon Aurora MySQL, Azure Database for MySQL, Google Cloud SQL MySQL).

Configuration
Host: mysql:3306
Database: mydb
User: grafana
Password: secret
Max open connections: 100
Max idle connections: 100
Connection max lifetime: 14400
Time series queries
SELECT
  UNIX_TIMESTAMP(time_col) as time_sec,
  value_col as value,
  name_col as metric
FROM my_table
WHERE $__timeFilter(time_col)
ORDER BY time_col ASC
Macros
MacroDescription
$__time(column)Converts column to Unix timestamp
$__timeFilter(column)Adds WHERE clause for dashboard time range
$__timeFrom()Start of dashboard time range as Unix timestamp
$__timeTo()End of dashboard time range as Unix timestamp
$__timeGroup(column, interval)Groups by time interval
$__timeGroupAlias(column, interval)As above, aliases as "time"
$__unixEpochFilter(column)Time filter for Unix epoch columns
$__intervalAuto-calculated interval for current time range
Example time series query
SELECT
  $__timeGroup(created_at, $__interval) AS time,
  status,
  count(*) AS cnt
FROM orders
WHERE $__timeFilter(created_at)
GROUP BY 1, 2
ORDER BY 1
Annotations
SELECT
  UNIX_TIMESTAMP(time) AS time,
  title AS text,
  tags
FROM events
WHERE $__timeFilter(time)

PostgreSQL

Configuration
Host: postgres:5432
Database: mydb
User: grafana
Password: secret
SSL mode: disable / require / verify-ca / verify-full
PostgreSQL time series
SELECT
  time_bucket('$__interval', time) AS time,
  avg(value)
FROM metrics
WHERE time BETWEEN $__timeFrom() AND $__timeTo()
GROUP BY 1
ORDER BY 1

Microsoft SQL Server

Configuration
Host: sqlserver:1433
Database: mydb
User: grafana
Password: secret
Encrypt: false / true / disable

InfluxDB

Supports InfluxDB 1.x (InfluxQL) and InfluxDB 2.x / 3.x (Flux).

InfluxDB 1.x (InfluxQL)
URL: http://influxdb:8086
Database: telegraf

Query example:

SELECT mean("value") FROM "measurement"
WHERE $timeFilter
GROUP BY time($interval), "host"
InfluxDB 2.x (Flux)
URL: http://influxdb:8086
Organization: myorg
Token: <api-token>
Default bucket: mydata

Flux query example:

from(bucket: "mydata")
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r._measurement == "cpu")
  |> filter(fn: (r) => r._field == "usage_idle")
  |> aggregateWindow(every: v.windowPeriod, fn: mean)

AWS CloudWatch

Configuration
# Auth options:
# - AWS SDK Default (instance role, ~/.aws/credentials, env vars)
# - Access & secret key (explicit credentials)
# - Assume role ARN

Default region: us-east-1

Required IAM permissions:

  • cloudwatch:GetMetricData

  • cloudwatch:ListMetrics

  • logs:* (for CloudWatch Logs)

CloudWatch Logs Insights
fields @timestamp, @message
| filter level = "ERROR"
| sort @timestamp desc
| limit 100

Azure Monitor

Requires Azure App Registration with:

  • Tenant ID, Client ID, Client Secret

  • Monitoring Reader role on target subscriptions/resource groups


Google Cloud Monitoring

Uses Google Cloud service account credentials (JSON key file or workload identity).


TestData (built-in)

A built-in data source for generating test/demo data without a real backend.

Use cases: Testing visualizations, demo dashboards, development without a real data source. Scenarios: Random walk, CSV metric values, streaming data, etc.


Graphite

URL: http://graphite:8080

Query examples:

target(servers.*.cpu)
averageSeries(servers.*.cpu)
groupByNode(servers.*.cpu, 1, 'averageSeries')

Jaeger (Tracing)

URL: http://jaeger:16686

Zipkin (Tracing)

URL: http://zipkin:9411

Pyroscope (Continuous Profiling)

URL: http://pyroscope:4040

Data Source Permissions (Enterprise)

By default, all org users can query any data source. With RBAC:

  • Assign specific users/teams to specific data sources

  • Configure at Data source settings > Permissions


Provisioning Data Sources (as Code)

# /etc/grafana/provisioning/datasources/prometheus.yaml
apiVersion: 1

datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    version: 1
    editable: false
    jsonData:
      timeInterval: "15s"
      queryTimeout: "60s"
      httpMethod: POST

  - name: Loki
    type: loki
    access: proxy
    url: http://loki:3100
    jsonData:
      maxLines: 1000
      derivedFields:
        - datasourceUid: tempo
          matcherRegex: "traceID=(\\w+)"
          name: TraceID
          url: "${__value.raw}"

  - name: MySQL Production
    type: mysql
    url: mysql:3306
    database: mydb
    user: grafana
    secureJsonData:
      password: "$GRAFANA_MYSQL_PASSWORD"
    jsonData:
      maxOpenConns: 100
      maxIdleConns: 100
      connMaxLifetime: 14400

Place YAML files in the provisioning directory; Grafana loads on startup and watches for changes.


Plugin Data Sources

Install additional data sources via:

  • Connections > Add new connection (search the plugin catalog)

  • grafana-cli plugins install <plugin-id>

  • Docker: set GF_INSTALL_PLUGINS environment variable

Popular plugin data sources:

  • grafana-opensearch-datasource - OpenSearch

  • grafana-bigquery-datasource - Google BigQuery

  • grafana-mongodb-datasource - MongoDB (Enterprise)

  • grafana-splunk-datasource - Splunk

  • grafana-datadog-datasource - Datadog

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs network access

Security

What our scanner noticed· Medium risk

  • References to credential files
  • Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Grafana Labs
Publisher
Grafana Labs (Official)
Source
grafana/skills · skills/grafana-core/grafana-oss · commit 8fb72a5
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Grafana Labs.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download grafana-oss.zip