OpenParable
Skip to content
← Back to skills

Grafana

DevOps & Security
grafana

Grafana is an Agent Skill for devops & security published in the BuilderIO/agent-native repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Query Grafana dashboards and Prometheus metrics for service health, LLM latency, and infrastructure monitoring. Use this skill when the user asks about service health, monitoring, alerts, or performance metrics.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/BuilderIO/agent-native/blob/HEAD/templates/analytics/.builder/skills/grafana/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/grafana, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Grafana Integration

Connection

  • Base URL: $GRAFANA_URL (e.g. https://your-org.grafana.net)
  • Auth: Authorization: Bearer $GRAFANA_API_TOKEN (service account token)
  • Credentials: GRAFANA_URL, GRAFANA_API_TOKEN from Settings → Data sources
  • Caching: 10-minute cache for metadata; query results are NOT cached (time-sensitive)
  • Key datasource: Prometheus UID grafanacloud-prom

Server Lib & API Routes

  • File: server/lib/grafana.ts

Exported Functions

FunctionDescription
listDashboards(query?)Search dashboards by query
getDashboard(uid)Full dashboard JSON with panels
getDatasources()List all datasources
getAlertRules()All alert rules (flattened from groups)
getAlertInstances()Currently firing alert instances
queryDatasource(uid, queries[], from?, to?)Proxy to Grafana's /api/ds/query

API Routes

RouteDescription
GET /api/grafana/dashboardsSearch dashboards
GET /api/grafana/dashboard?uid=...Full dashboard JSON
GET /api/grafana/datasourcesList datasources
GET /api/grafana/alertsAlert rules and firing instances
POST /api/grafana/queryQuery datasource (Prometheus, Loki, etc.)

Agent Action

Use grafana for agent-facing Grafana work. Do not call /api/grafana/* directly from the agent.

ModeArgsDescription
dashboardssearchSearch dashboards
dashboarduidFull dashboard JSON
datasourcesList datasources
alertsAlert rules and firing instances
querydatasourceUid, queries, from, toQuery a datasource

Dashboard

  • /adhoc/engineering — Engineering dashboard (mirrors a Grafana dashboard by UID)

Grafana Response Frame Format

{ results: { [refId]: { frames: [{ schema: { fields }, data: { values } }] } } }
  • values[0] = timestamps (epoch ms), values[1+] = metric values
  • Series labels from schema.fields[i].labels (e.g. { model: "claude-3.5" })
  • Transform to Recharts: { time: number, [seriesName]: number }[]

Template Variables

  • $CodegenMode → default quality-v4
  • $AIModel → regex pattern, default .* (all)
  • $environment → cloud or cloud-v2, default cloud
  • Variables interpolated via string replace before querying

Key Prometheus Metrics

  • Codegen: vcpcodegen_completion_total, vcpcodegen_completion_latency_bucket, vcpcodegen_feedback_total, vcpcodegen_error_total
  • LLM: llm_completion_cost_total, llm_input_tokens_total, llm_output_tokens_total, llm_latency_bucket, llm_failures_total, llm_completions_total
  • Projects: projects_proposed_config_total, projects_status_total, projects_remote_machine_*, projects_start_duration_bucket
  • API/Runtime: api_request_total, with_span_duration_bucket, memory_heap_usage_percent_bucket
  • Fly.io: fly_endpoint_total, fly_machine_*
  • GitHub: builderbot_pr_created_total, builderbot_pr_closed_total

Key Patterns & Gotchas

  • queryDatasource constructs body with datasource UID in each query target; timestamps as string ms
  • getAlertRules flattens nested rule groups from unified alerting API
  • getAlertInstances handles both array and wrapped object response shapes
  • POST helper caches by default (fine for idempotent endpoints) but queryDatasource skips cache
  • Heatmap panels render as multi-series line/area (Recharts has no native heatmap; PromQL histogram_quantile() computes quantiles)

Incident Investigation Pattern

For production issues, query Grafana/Prometheus FIRST:

  1. LLM latency by model (llm_latency_bucket)
  2. Request rates (api_request_total)
  3. Error rates (llm_failures_total)
  4. Instance counts (via Cloud Monitoring)

Then check Sentry for application errors, Cloud Logging for raw logs.