대시보드 JSON 모델

대시보드 JSON 모델 (Dashboard JSON model)

Grafana 대시보드는 메타데이터, 패널, 변수, 설정을 저장하는 JSON 객체로 표현돼요. 이 문서는 대시보드 JSON 스키마 모델의 종류와 각 필드의 용도를 설명합니다. 최신 스키마(V2 Resource)부터 클래식(Classic) 모델까지 다루며, JSON을 직접 편집해 대시보드를 관리하고 싶을 때 유용해요.

출처: Dashboard JSON model

본문

다양한 대시보드 스키마 모델 (Different dashboard schema models)

현재 세 가지 대시보드 JSON 스키마 모델이 있어요.

• V2 Resource: 현재 스키마로, 고급 레이아웃과 조건부 렌더링 같은 새 기능을 지원해요. 모든 대시보드 요소를 Kubernetes kind로 모델링하며, Kubernetes 규칙에 따라 대시보드 컴포넌트를 선언해요.
• V1 Resource: Kubernetes 스타일 리소스로 포맷된 Classic 대시보드 스키마. spec 속성이 스키마의 Classic 모델을 포함해요. Grafana v12.2.0과 v13.0.0 사이 API 통신의 기본 형식이며 대시보드 내보내기·가져오기·공유에 사용됐어요.
• Classic: Kubernetes 리소스가 아니며 Grafana v12.2.0 이전의 기본 모델. grafana.com/dashboards의 Grafana 대시보드 컬렉션에서 대시보드 내보내기·가져오기·공유에 널리 사용됐어요. 이 모델로 만든 대시보드는 이 모델 또는 V2로 내보낼 수 있어요.

참고: Observability as Code는 JSON 모델의 두 버전 모두와 동작하지만, 버전 2와 완전히 호환돼요.

JSON 모델 접근 및 업데이트 (Access and update the JSON model)

대시보드의 JSON 표현에 접근하려면:

1. 대시보드로 이동해요.
2. 오른쪽 상단에서 Edit을 클릭해요.
3. 도구 모음에서 Dashboard options 아이콘을 클릭해요.
4. 사이드바에서 Settings을 클릭해요.
5. JSON Model 탭으로 이동해요.
6. JSON 업데이트를 끝내면 탭 하단의 Save changes를 클릭해요.
7. Back and Exit edit을 클릭해요.

V2 Resource 모델

V2 Resource 모델 스키마의 상세 내용은 Swagger 문서를 참고하세요. Grafana Cloud 인스턴스에서도 https://grafana.com/launch/swagger에서 Swagger 스키마 문서에 접근할 수 있어요.

V1 Resource 모델

V1 Resource 스키마 모델은 Classic JSON 모델 스키마를 Kubernetes 스타일 리소스로 포맷해요. 스키마의 spec 속성이 스키마의 Classic 스타일 모델을 포함해요. 상세 내용은 Swagger 문서를 참고하세요.

다음 코드 스니펫은 V1 Resource 모델에 포함된 필드를 보여 줘요.

{
  "apiVersion": "dashboard.grafana.app/v1",
  "kind": "Dashboard",
  "metadata": {
    "name": "isnt5ss",
    "namespace": "stacks-521104",
    "uid": "92674c0e-0360-4bb4-99ab-fb150581376d",
    "resourceVersion": "1764705030717045",
    "generation": 1,
    "creationTimestamp": "2025-12-02T19:50:30Z",
    "labels": {
      "grafana.app/deprecatedInternalID": "1329"
    },
    "annotations": {
      "grafana.app/createdBy": "user:u000000002",
      "grafana.app/folder": "",
      "grafana.app/saved-from-ui": "Grafana Cloud (instant)"
    }
  },
  "spec": {
    "annotations": {
      "list": [
        {
          "builtIn": 1,
          "datasource": {
            "type": "grafana",
            "uid": "-- Grafana --"
          },
          "enable": true,
          "hide": true,
          "iconColor": "rgba(0, 211, 255, 1)",
          "name": "Annotations & Alerts",
          "type": "dashboard"
        }
      ]
    },
    "editable": true,
    "fiscalYearStartMonth": 0,
    "graphTooltip": 0,
    "id": 1329,
    "links": [],
    "panels": [],
    "preload": false,
    "schemaVersion": 42,
    "tags": [],
    "templating": {
      "list": []
    },
    "time": {
      "from": "now-6h",
      "to": "now"
    },
    "timepicker": {},
    "timezone": "Africa/Abidjan",
    "title": "Graphite suggestions",
    "uid": "isnt5ss",
    "version": 1,
    "weekStart": ""
  },
  "status": {}
}

Classic 모델

자체 관리 Grafana에서 새 대시보드를 만들면 새 대시보드 JSON 객체가 다음 필드로 초기화돼요.

참고: 다음 JSON에서 id는 대시보드 저장 전까지 기본값으로 할당된 null로 표시돼요. 대시보드가 저장된 후 정수 값이 id 필드에 할당돼요.

{
  "id": null,
  "uid": "cLV5GDCkz",
  "title": "New dashboard",
  "tags": [],
  "timezone": "browser",
  "editable": true,
  "graphTooltip": 1,
  "panels": [],
  "time": {
    "from": "now-6h",
    "to": "now"
  },
  "timepicker": {
    "refresh_intervals": []
  },
  "templating": {
    "list": []
  },
  "annotations": {
    "list": []
  },
  "refresh": "5s",
  "schemaVersion": 17,
  "version": 0,
  "links": []
}

대시보드 JSON의 각 필드는 사용법과 함께 아래에 설명돼요.

패널 (Panels)

패널은 대시보드의 구성 요소예요. 데이터 소스 쿼리, 그래프 유형, 별칭 등으로 구성돼요. 패널 JSON은 각각 다른 패널을 나타내는 JSON 객체의 배열로 구성돼요. 대부분의 필드는 모든 패널에 공통이지만 일부 필드는 패널 유형에 따라 달라요. 다음은 텍스트 패널의 패널 JSON 예시예요.

"panels": [
  {
    "type": "text",
    "title": "Panel Title",
    "gridPos": {
      "x": 0,
      "y": 0,
      "w": 12,
      "h": 9
    },
    "id": 4,
    "mode": "markdown",
    "content": "# title"
  }
]

패널 크기와 위치 (Panel size and position):

gridPos 속성은 그리드 좌표로 패널 크기와 위치를 설명해요.

• w 1-24 (대시보드 너비는 24개 열로 나뉨)
• h 그리드 높이 단위, 각각 30픽셀
• x w와 같은 단위의 x 위치
• y h와 같은 단위의 y 위치

그리드는 패널 위에 빈 공간이 있으면 패널을 위로 이동시키는 "음의 중력"(negative gravity)을 가져요.

timepicker

"timepicker": {
    "collapse": false,
    "enable": true,
    "notice": false,
    "now": true,
    "hidden": false,
    "nowDelay": "",
    "quick_ranges": [
      {
        "display": "Last 6 hours",
        "from": "now-6h",
        "to": "now"
      },
      {
        "display": "Last 7 days",
        "from": "now-7d",
        "to": "now"
      }
    ],
    "refresh_intervals": [
      "5s", "10s", "30s", "1m", "5m", "15m", "30m", "1h", "2h", "1d"
    ],
    "status": "Stable",
    "type": "timepicker"
  }

templating

templating 필드는 저장된 값과 함께 템플릿 변수의 배열과 기타 메타데이터를 포함해요.

 "templating": {
    "enable": true,
    "list": [
      {
        "allFormat": "wildcard",
        "current": {
          "tags": [],
          "text": "prod",
          "value": "prod"
        },
        "datasource": null,
        "includeAll": true,
        "name": "env",
        "options": [
          {
            "selected": false,
            "text": "All",
            "value": "*"
          },
          { "selected": false, "text": "stage", "value": "stage" },
          { "selected": false, "text": "test", "value": "test" }
        ],
        "query": "tag_values(cpu.utilization.average,env)",
        "refresh": false,
        "type": "query"
      },
      {
        "allFormat": "wildcard",
        "current": { "text": "apache", "value": "apache" },
        "datasource": null,
        "includeAll": false,
        "multi": false,
        "multiFormat": "glob",
        "name": "app",
        "options": [
          { "selected": true, "text": "tomcat", "value": "tomcat" },
          { "selected": false, "text": "cassandra", "value": "cassandra" }
        ],
        "query": "tag_values(cpu.utilization.average,app)",
        "refresh": false,
        "regex": "",
        "type": "query"
      }
    ]
  }

templating 섹션의 필드 사용법:

더 알아보기 (Learn more)

• 대시보드 만들기
• 변수
• 패널
• 주석
• Swagger 문서