---

name: build-grafana-dashboards description: > Crea dashboards de Grafana listos para producción con paneles reutilizables, variables de plantilla, anotaciones y aprovisionamiento para despliegue controlado por versiones. Útil para crear representaciones visuales de métricas de Prometheus, Loki u otras fuentes de datos, construir dashboards operacionales para equipos SRE, migrar de creación manual a aprovisionamiento controlado por versiones, o establecer informes de cumplimiento SLO a nivel ejecutivo. locale: es source_locale: en source_commit: 6f65f316 fence_basis_commit: 6f65f316 translator: claude-opus-4-6 translation_date: 2026-03-16 license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: observability complexity: intermediate language: multi tags: grafana, dashboards, visualization, panels, provisioning

Construir Dashboards de Grafana

Diseña y despliega dashboards de Grafana con buenas prácticas de mantenibilidad, reutilización y control de versiones.

Cuándo Usar

• Crear representaciones visuales de métricas de Prometheus, Loki u otras fuentes de datos
• Construir dashboards operacionales para equipos SRE y equipos de respuesta a incidentes
• Establecer dashboards de informes a nivel ejecutivo para cumplimiento de SLO
• Migrar dashboards de creación manual a aprovisionamiento controlado por versiones
• Estandarizar diseños de dashboards entre equipos con variables de plantilla
• Crear experiencias de desglose desde resúmenes generales hasta métricas detalladas

Entradas

• Requerido: Configuración de fuente de datos (Prometheus, Loki, Tempo, etc.)
• Requerido: Métricas o logs a visualizar con sus patrones de consulta
• Opcional: Variables de plantilla para vistas de múltiples servicios o entornos
• Opcional: JSON de dashboard existente para migración o modificación
• Opcional: Consultas de anotación para correlación de eventos (despliegues, incidentes)

Procedimiento

Consulta Ejemplos Extendidos para archivos de configuración completos y plantillas.

Paso 1: Diseñar la Estructura del Dashboard

Planifica el diseño y la organización del dashboard antes de construir los paneles.

Crea un documento de especificación del dashboard:

# Service Overview Dashboard

## Purpose
Real-time operational view for on-call engineers monitoring the API service.

## Rows
1. High-Level Metrics (collapsed by default)
   - Request rate, error rate, latency (RED metrics)
   - Service uptime, instance count
2. Detailed Metrics (expanded by default)
   - Per-endpoint latency breakdown
   - Error rate by status code
   - Database connection pool status
3. Resource Utilization
   - CPU, memory, disk usage per instance
   - Network I/O rates
4. Logs (collapsed by default)
   - Recent errors from Loki
   - Alert firing history

## Variables
- `environment`: production, staging, development
- `instance`: all instances or specific instance selection
- `interval`: aggregation window (5m, 15m, 1h)

## Annotations
- Deployment events from CI/CD system
- Alert firing/resolving events

Principios clave de diseño:

• Métricas más importantes primero: Métricas críticas en la parte superior, detalles abajo
• Rangos de tiempo consistentes: Sincronizar el tiempo entre todos los paneles
• Rutas de desglose: Enlazar desde resúmenes generales hasta dashboards detallados
• Diseño adaptable: Usar filas y anchos de panel que funcionen en varias pantallas

Esperado: Estructura de dashboard documentada claramente, partes interesadas alineadas en métricas y prioridades de diseño.

En caso de fallo:

• Realizar revisión del diseño del dashboard con usuarios finales (SREs, desarrolladores)
• Comparar con estándares de la industria (método USE, método RED, Four Golden Signals)
• Revisar dashboards existentes del equipo para patrones de consistencia

Paso 2: Crear el Dashboard con Variables de Plantilla

Construye la base del dashboard con variables reutilizables para filtrado.

Crea la estructura JSON del dashboard (o usa la interfaz y luego exporta):

{
  "dashboard": {
    "title": "API Service Overview",
    "uid": "api-service-overview",
    "version": 1,
    "timezone": "browser",
    "editable": true,
    "graphTooltip": 1,
    "time": {
      "from": "now-6h",
      "to": "now"
    },
    "refresh": "30s",
    "templating": {
      "list": [
        {
          "name": "environment",
          "type": "query",
          "datasource": "Prometheus",
          "query": "label_values(up{job=\"api-service\"}, environment)",
          "multi": false,
          "includeAll": false,
          "refresh": 1,
          "sort": 1,
          "current": {
            "selected": false,
            "text": "production",
            "value": "production"
          }
        },
        {
          "name": "instance",
          "type": "query",
          "datasource": "Prometheus",
          "query": "label_values(up{job=\"api-service\",environment=\"$environment\"}, instance)",
          "multi": true,
          "includeAll": true,
          "refresh": 1,
          "allValue": ".*",
          "current": {
            "selected": true,
            "text": "All",
            "value": "$__all"
          }
        },
        {
          "name": "interval",
          "type": "interval",
          "options": [
            {"text": "1m", "value": "1m"},
            {"text": "5m", "value": "5m"},
            {"text": "15m", "value": "15m"},
            {"text": "1h", "value": "1h"}
          ],
          "current": {
            "text": "5m",
            "value": "5m"
          },
          "auto": false
        }
      ]
    },
    "annotations": {
      "list": [
        {
          "name": "Deployments",
          "datasource": "Prometheus",
          "enable": true,
          "expr": "changes(app_version{job=\"api-service\",environment=\"$environment\"}[5m]) > 0",
          "step": "60s",
          "iconColor": "rgba(0, 211, 255, 1)",
          "tagKeys": "version"
        }
      ]
    }
  }
}

Tipos de variables y casos de uso:

• Variables de consulta: Listas dinámicas desde la fuente de datos (label_values(), query_result())
• Variables de intervalo: Ventanas de agregación para consultas
• Variables personalizadas: Listas estáticas para selecciones no métricas
• Variables constantes: Valores compartidos entre paneles (nombres de fuentes de datos, umbrales)
• Variables de caja de texto: Entrada libre para filtrado

Esperado: Las variables se llenan correctamente desde la fuente de datos, los filtros en cascada funcionan (el entorno filtra instancias), las selecciones predeterminadas son apropiadas.

En caso de fallo:

• Probar consultas de variables independientemente en la interfaz de Prometheus
• Verificar dependencias circulares (variable A depende de B depende de A)
• Verificar patrones de regex en el campo allValue para variables de selección múltiple
• Revisar configuración de actualización de variables (al cargar el dashboard vs al cambiar el rango de tiempo)

Paso 3: Construir Paneles de Visualización

Crea paneles para cada métrica con tipos de visualización apropiados.

Panel de series de tiempo (tasa de solicitudes):

{
  "type": "timeseries",
  "title": "Request Rate",
  "gridPos": {"h": 8, "w": 12, "x": 0, "y": 0},
  "targets": [
    {
      "expr": "sum(rate(http_requests_total{job=\"api-service\",environment=\"$environment\",instance=~\"$instance\"}[$interval])) by (method)",
      "legendFormat": "{{method}}",
      "refId": "A"
    }
  ],
  "fieldConfig": {
    "defaults": {
      "unit": "reqps",
      "color": {
        "mode": "palette-classic"
      },
      "custom": {
        "drawStyle": "line",
        "lineInterpolation": "smooth",
        "fillOpacity": 10,
        "spanNulls": true
      },
      "thresholds": {
        "mode": "absolute",
        "steps": [
          {"value": null, "color": "green"},
          {"value": 1000, "color": "yellow"},
          {"value": 5000, "color": "red"}
        ]
      }
    }
  },
  "options": {
    "tooltip": {
      "mode": "multi",
      "sort": "desc"
    },
    "legend": {
      "displayMode": "table",
      "placement": "right",
      "calcs": ["mean", "max", "last"]
    }
  }
}

Panel estadístico (tasa de errores):

{
  "type": "stat",
  "title": "Error Rate",
  "gridPos": {"h": 4, "w": 6, "x": 12, "y": 0},
  "targets": [
    {
# ... (see EXAMPLES.md for complete configuration)

Panel de mapa de calor (distribución de latencia):

{
  "type": "heatmap",
  "title": "Request Duration Heatmap",
  "gridPos": {"h": 8, "w": 12, "x": 0, "y": 8},
  "targets": [
    {
# ... (see EXAMPLES.md for complete configuration)

Guía de selección de paneles:

• Series de tiempo: Tendencias a lo largo del tiempo (tasas, conteos, duraciones)
• Estadístico: Valor actual único con coloración por umbrales
• Medidor: Valores porcentuales (CPU, memoria, uso de disco)
• Medidor de barras: Comparar múltiples valores en un punto en el tiempo
• Mapa de calor: Distribución de valores a lo largo del tiempo (percentiles de latencia)
• Tabla: Desglose detallado de múltiples métricas
• Logs: Líneas de log sin procesar de Loki con filtrado

Esperado: Los paneles se renderizan correctamente con datos, las visualizaciones coinciden con los tipos de métricas previstos, las leyendas son descriptivas, los umbrales resaltan problemas.

En caso de fallo:

• Probar consultas en la vista Explorar con el mismo rango de tiempo y variables
• Verificar errores tipográficos en nombres de métricas o filtros de etiquetas incorrectos
• Verificar que las funciones de agregación coincidan con el tipo de métrica (rate para contadores, avg para medidores)
• Revisar configuraciones de unidades (bytes, segundos, solicitudes por segundo)
• Habilitar "Show query inspector" para depurar resultados vacíos

Paso 4: Configurar Filas y Diseño

Organiza los paneles en filas colapsables para agrupación lógica.

{
  "panels": [
    {
      "type": "row",
      "title": "High-Level Metrics",
      "collapsed": false,
# ... (see EXAMPLES.md for complete configuration)

Buenas prácticas de diseño:

• La cuadrícula tiene 24 unidades de ancho, cada panel especifica w (ancho) y h (altura)
• Usa filas para agrupar paneles relacionados, colapsar secciones menos críticas por defecto
• Coloca las métricas más críticas en el primer área visible (y=0-8)
• Mantener alturas de panel consistentes dentro de las filas (típicamente 4, 8 o 12 unidades)
• Usa ancho completo (24) para series de tiempo, medio ancho (12) para comparaciones

Esperado: El diseño del dashboard está organizado lógicamente, las filas colapsan/expanden correctamente, los paneles se alinean visualmente sin espacios.

En caso de fallo:

• Validar que las coordenadas gridPos no se superpongan
• Verificar que el arreglo de paneles de fila contenga paneles (no nulo)
• Verificar que las coordenadas y incrementen lógicamente hacia abajo en la página
• Usar la interfaz de Grafana "Edit JSON" para inspeccionar posiciones de cuadrícula

Paso 5: Agregar Vínculos y Desglose

Crea rutas de navegación entre dashboards relacionados.

Vínculos a nivel de dashboard en JSON:

{
  "links": [
    {
      "title": "Service Details",
      "type": "link",
      "icon": "external link",
# ... (see EXAMPLES.md for complete configuration)

Vínculos de datos a nivel de panel:

{
  "fieldConfig": {
    "defaults": {
      "links": [
        {
          "title": "View Logs for ${__field.labels.instance}",
# ... (see EXAMPLES.md for complete configuration)

Variables de vínculos:

• $service, $environment: Variables de plantilla del dashboard
• ${__field.labels.instance}: Valor de etiqueta desde el punto de datos clicado
• ${__from}, ${__to}: Rango de tiempo actual del dashboard
• $__url_time_range: Rango de tiempo codificado para URL

Esperado: Al hacer clic en elementos de paneles o vínculos del dashboard se navega a vistas relacionadas con el contexto preservado (rango de tiempo, variables).

En caso de fallo:

• Codificar en URL los caracteres especiales en parámetros de consulta
• Probar vínculos con varias selecciones de variables (Todas vs valor específico)
• Verificar que los UIDs de los dashboards de destino existan y sean accesibles
• Comprobar que los indicadores includeVars y keepTime funcionen según lo esperado

Paso 6: Configurar el Aprovisionamiento del Dashboard

Controla los dashboards como código para despliegues reproducibles.

Crea la estructura de directorios de aprovisionamiento:

mkdir -p /etc/grafana/provisioning/{dashboards,datasources}

Aprovisionamiento de fuente de datos (/etc/grafana/provisioning/datasources/prometheus.yml):

apiVersion: 1

datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
# ... (see EXAMPLES.md for complete configuration)

Aprovisionamiento de dashboard (/etc/grafana/provisioning/dashboards/default.yml):

apiVersion: 1

providers:
  - name: 'default'
    orgId: 1
    folder: 'Services'
    type: file
    disableDeletion: false
    updateIntervalSeconds: 30
    allowUiUpdates: true
    options:
      path: /var/lib/grafana/dashboards
      foldersFromFilesStructure: true

Almacena los archivos JSON del dashboard en /var/lib/grafana/dashboards/:

/var/lib/grafana/dashboards/
├── api-service/
│   ├── overview.json
│   └── details.json
├── database/
│   └── postgres.json
└── infrastructure/
    ├── nodes.json
    └── kubernetes.json

Usando Docker Compose:

version: '3.8'
services:
  grafana:
    image: grafana/grafana:10.2.0
    ports:
      - "3000:3000"
    volumes:
      - ./grafana/provisioning:/etc/grafana/provisioning
      - ./grafana/dashboards:/var/lib/grafana/dashboards
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
      - GF_USERS_ALLOW_SIGN_UP=false
      - GF_AUTH_ANONYMOUS_ENABLED=true
      - GF_AUTH_ANONYMOUS_ORG_ROLE=Viewer

Esperado: Los dashboards se cargan automáticamente al iniciar Grafana, los cambios en archivos JSON se reflejan después del intervalo de actualización, el control de versiones registra los cambios del dashboard.

En caso de fallo:

• Verificar los logs de Grafana: docker logs grafana | grep -i provisioning
• Verificar la sintaxis JSON: python -m json.tool dashboard.json
• Asegurarse de que los permisos de archivo permitan a Grafana leer: chmod 644 *.json
• Probar con allowUiUpdates: false para evitar modificaciones desde la interfaz
• Validar la configuración de aprovisionamiento: curl http://localhost:3000/api/admin/provisioning/dashboards/reload -X POST -H "Authorization: Bearer $GRAFANA_API_KEY"

Validación

• El dashboard carga sin errores en la interfaz de Grafana
• Todas las variables de plantilla se llenan con los valores esperados
• La cascada de variables funciona (seleccionar entorno filtra instancias)
• Los paneles muestran datos para los rangos de tiempo configurados
• Las consultas de paneles usan variables correctamente (sin valores codificados)
• Los umbrales resaltan estados problemáticos apropiadamente
• El formato de leyenda es descriptivo y no está sobrecargado
• Las anotaciones aparecen para eventos relevantes
• Los vínculos navegan a dashboards correctos con el contexto preservado
• El dashboard está aprovisionado desde un archivo JSON (controlado por versiones)
• El diseño adaptable funciona en diferentes tamaños de pantalla
• Las interacciones de información en pantalla y al pasar el cursor proporcionan contexto útil

Errores Comunes

• Variable que no actualiza paneles: Asegúrate de que las consultas usen la sintaxis $variable, no valores codificados. Verificar la configuración de actualización de variables.
• Paneles vacíos con consulta correcta: Verificar que el rango de tiempo incluya puntos de datos. Verificar el intervalo de recopilación frente a la ventana de agregación (la tasa de 5m necesita >5m de datos).
• Leyenda demasiado verbosa: Usar legendFormat para mostrar solo las etiquetas relevantes, no el nombre completo de la métrica. Ejemplo: {{method}} - {{status}} en lugar del predeterminado.
• Rangos de tiempo inconsistentes: Establecer sincronización de tiempo del dashboard para que todos los paneles compartan la misma ventana de tiempo. Usar "Sync cursor" para investigación correlacionada.
• Problemas de rendimiento: Evitar consultas que devuelvan series de alta cardinalidad (>1000). Usar reglas de grabación o pre-agregación. Limitar los rangos de tiempo para consultas costosas.
• Deriva del dashboard: Sin aprovisionamiento, los cambios manuales en la interfaz crean conflictos en el control de versiones. Usar allowUiUpdates: false en producción.
• Vínculos de datos faltantes: Los vínculos de datos requieren nombres de etiquetas exactos. Usar ${__field.labels.labelname} con cuidado, verificar que la etiqueta existe en el resultado de la consulta.
• Sobrecarga de anotaciones: Demasiadas anotaciones saturan la vista. Filtrar anotaciones por importancia o usar pistas de anotación separadas.

Habilidades Relacionadas

• setup-prometheus-monitoring - Configurar fuentes de datos de Prometheus que alimentan los dashboards de Grafana
• configure-log-aggregation - Configurar Loki para consultas de paneles de log y anotaciones basadas en log
• define-slo-sli-sla - Visualizar el cumplimiento de SLO y los presupuestos de error con paneles de estadísticas y medidores de Grafana
• instrument-distributed-tracing - Agregar vínculos de ID de traza desde paneles de métricas a vistas de traza de Tempo