Grafana Oss
Grafana LabsOfficialPublished by Grafana Labs
- Skill
- Tool integration
- Cloud and DevOps
- Apache-2.0
- Medium risk
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
Download the skill as a ZIP:
https://autogineer.com/agent-skills/grafana/grafana-oss/downloadUnzip 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
Common Workflows
Provisioning dashboards from disk
Drop dashboard JSON file(s) under
/var/lib/grafana/dashboards/Add a provider in
provisioning/dashboards/default.yaml(see § Dashboard provisioning below)Restart Grafana so the provider config is loaded
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
Write
provisioning/datasources/datasources.yaml(see § Data source provisioning below)Restart Grafana
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
Provision via YAML or
POST /api/serviceaccounts(full API in references/api.md § Users + service accounts)Mint a token via
POST /api/serviceaccounts/{id}/tokensVerify 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: trueFor 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:4040RBAC (built-in roles)
| Role | Permissions |
|---|---|
| Viewer | Read dashboards, alerts |
| Editor | Create/edit dashboards, alerts |
| Admin | Manage data sources, users, plugins |
| GrafanaAdmin | Server-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:4040After 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-codereferences/datasources.md— data source setup and query examples for Prometheus, Loki, Tempo, SQL, CloudWatch, and pluginsreferences/panel-types.md— panel-type table + decision guide for picking the right onereferences/panels.md— panel editor, visualization options, field config, transformations, query options, inspection, and performance tipsreferences/alerting.md— alerting concepts, contact points, notification policies, templates, silences, and common rule examplesreferences/api.md— full Grafana OSS API reference (dashboards, data sources, users, service accounts, annotations) with verification curls and common failure modesreferences/config.md—grafana.iniserver / database / SMTP / auth / security / feature-toggle config + restart-required issues
Files
- ATTRIBUTION.mdAdded by AutoGineer842 B
- LICENSELicence file added by AutoGineer11.1 KiB
- SKILL.md6.0 KiB
- references/alerting.md11.2 KiB
- references/api.md2.7 KiB
- references/config.md2.3 KiB
- references/dashboard-json.md2.1 KiB
- references/dashboards.md6.1 KiB
- references/datasources.md9.8 KiB
- references/panel-types.md1.2 KiB
- references/panels.md10.3 KiB
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
Go to Connections > Data sources (or Configuration > Data sources in older versions)
Click Add new data source
Search for and select the data source type
Fill in connection details (URL, credentials, etc.)
Click Save & Test to verify the connection
Data source settings (common to all types)
| Setting | Description |
|---|---|
| Name | Display name used in dashboards |
| Default | If checked, pre-selected in new panels |
| HTTP URL | The endpoint for the data source server |
| Auth | Basic 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
| Option | Description |
|---|---|
| Scrape interval | Default: 15s - should match your Prometheus scrape interval |
| Query timeout | Default: 60s |
| Exemplars | Enable to link metrics to traces |
| Ruler URL | For 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 valuesExemplars
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: 1000Derived 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 selectorTempo (Distributed Tracing)
Configuration
URL: http://tempo:3200Key options
| Option | Description |
|---|---|
| Trace to logs | Link traces to Loki logs via trace ID |
| Trace to metrics | Link trace spans to Prometheus metrics |
| Service graph | Enable service dependency graph |
| Node graph | Show 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 CortexElasticsearch / OpenSearch
Configuration
URL: http://elasticsearch:9200
Index name: logs-*
Time field name: @timestamp
Elasticsearch version: 8.xMySQL
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: 14400Time 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 ASCMacros
| Macro | Description |
|---|---|
$__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 |
$__interval | Auto-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 1Annotations
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-fullPostgreSQL time series
SELECT
time_bucket('$__interval', time) AS time,
avg(value)
FROM metrics
WHERE time BETWEEN $__timeFrom() AND $__timeTo()
GROUP BY 1
ORDER BY 1Microsoft SQL Server
Configuration
Host: sqlserver:1433
Database: mydb
User: grafana
Password: secret
Encrypt: false / true / disableInfluxDB
Supports InfluxDB 1.x (InfluxQL) and InfluxDB 2.x / 3.x (Flux).
InfluxDB 1.x (InfluxQL)
URL: http://influxdb:8086
Database: telegrafQuery 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: mydataFlux 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-1Required IAM permissions:
cloudwatch:GetMetricDatacloudwatch:ListMetricslogs:*(for CloudWatch Logs)
CloudWatch Logs Insights
fields @timestamp, @message
| filter level = "ERROR"
| sort @timestamp desc
| limit 100Azure Monitor
Requires Azure App Registration with:
Tenant ID, Client ID, Client Secret
Monitoring Readerrole 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:8080Query examples:
target(servers.*.cpu)
averageSeries(servers.*.cpu)
groupByNode(servers.*.cpu, 1, 'averageSeries')Jaeger (Tracing)
URL: http://jaeger:16686Zipkin (Tracing)
URL: http://zipkin:9411Pyroscope (Continuous Profiling)
URL: http://pyroscope:4040Data 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: 14400Place 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_PLUGINSenvironment variable
Popular plugin data sources:
grafana-opensearch-datasource- OpenSearchgrafana-bigquery-datasource- Google BigQuerygrafana-mongodb-datasource- MongoDB (Enterprise)grafana-splunk-datasource- Splunkgrafana-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 or Grafana Labs.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download grafana-oss.zip