API로 대시보드 만들기 및 관리

이 문서에서는 Cloud Monitoring API에서 Dashboard 리소스를 사용하여 커스텀 대시보드와 해당 대시보드의 위젯을 만들고 관리하는 방법을 설명합니다. 여기에 있는 예시에서는 curl을 사용하여 API를 호출하여 대시보드를 관리하는 방법과 Google Cloud CLI를 사용하는 방법을 보여줍니다. Google Cloud 콘솔을 통해 커스텀 대시보드를 관리할 수도 있지만 API를 사용하면 수많은 대시보드를 프로그래매틱 방식으로 동시에 관리할 수 있습니다.

엔드포인트는 대시보드를 관리하고 구성하기 위해 다음 메서드를 지원합니다.

dashboards.create: 대시보드를 만듭니다.
dashboards.delete: 지정된 대시보드를 삭제합니다.
dashboards.list: 특정 프로젝트의 모든 대시보드 목록을 검색합니다.
dashboards.get: 지정된 대시보드를 검색합니다.
dashboards.patch: 지정된 대시보드의 구조를 업데이트합니다.

curl 유틸리티를 사용하거나 Google Cloud CLI를 사용하여 API를 직접 호출할 수 있습니다.

사전 정의된 대시보드를 검색, 수정 또는 삭제할 수 없습니다.

시작하기 전에

대시보드를 만들 때는 표시할 구성요소 또는 위젯과 해당 위젯의 레이아웃을 지정해야 합니다. 또한 대시보드에 영구 필터를 추가할 수 있습니다.

대시보드 레이아웃

레이아웃은 대시보드 구성요소의 정렬 방법을 정의합니다. 이 API는 다음 레이아웃을 제공합니다.

GridLayout: 사용 가능한 공간을 동일한 너비의 세로 열로 나누고 행 우선 전략을 사용하여 위젯 집합을 정렬합니다.
MosaicLayout: 사용 가능한 공간을 그리드로 나눕니다. 각 위젯은 하나 이상의 그리드 블록을 차지할 수 있습니다.
RowLayout: 사용 가능한 공간을 행으로 나누고 각 행에 위젯 집합을 가로로 정렬합니다.
ColumnLayout: 사용 가능한 공간을 세로 열로 나누고 각 열에서 위젯 집합을 세로로 배열합니다.

예를 들어 다음은 3개의 Text 위젯을 사용하여 RowLayout의 대시보드를 JSON으로 표현한 것입니다.

{
  "displayName": "Row-layout example",
  "rowLayout": {
    "rows": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  }
}

대시보드 위젯

위젯에는 단일 대시보드 구성요소와 대시보드에 구성요소를 표시하는 방법의 구성이 포함됩니다. 대시보드에는 두 개 이상의 위젯이 있을 수 있습니다. Widget 객체에는 여러 가지 유형이 있습니다.

차트 및 표 위젯:
- XyChart: X축과 Y축을 사용하여 데이터를 표시합니다. 다음 차트는 XyChart 위젯의 인스턴스입니다.
- 선 차트
- 막대 그래프
- 누적 영역 차트
- 히트맵
- 로그 애널리틱스 차트
- SLO 위젯이지만 API를 사용한 SLO 차트 만들기는 지원되지 않습니다.
선 차트, 누적 막대 그래프, 누적 영역 차트를 만드는 경우 측정항목이 왼쪽 또는 오른쪽 Y축을 참조하도록 지정할 수 있습니다. 여러 측정항목을 차트로 표시할 때 Y축을 모두 사용할 수 있습니다.
- PieChart: 측정항목의 최신 값을 표시하며, 각 시계열은 원형 차트의 한 조각에 해당합니다.
- Scorecard: 측정항목의 최신 값과 이 값이 하나 이상의 기준과 관련되는 방식을 표시합니다.
- TimeSeriesTable: 측정항목의 최신 값을 표시합니다. 열을 기준으로 테이블을 정렬하고, 테이블을 필터링하고, 디스플레이에서 열을 추가하거나 삭제할 수 있습니다.
알림 차트 및 이슈 위젯:
- AlertChart: 단일 조건 알림 정책의 요약을 표시합니다. 이 위젯은 데이터를 선 차트로 표시하고, 기준점을 표시하고, 열린 이슈 수를 나열합니다.
- IncidentList: 이슈 목록을 표시합니다. 특정 알림 정책 또는 특정 리소스 유형에 대한 이슈를 표시하도록 위젯을 구성할 수 있습니다.
로그 및 오류 위젯:
- ErrorReportingPanel: 선택한 Google Cloud 프로젝트에 저장된 오류 그룹을 표시합니다.
- LogsPanel: 현재 Google Cloud 프로젝트에 저장된 프로젝트 범위 로그 항목을 표시합니다. 현재 측정항목 범위를 통해 액세스할 수 있는 Google Cloud 프로젝트에 저장된 로그 항목을 표시하도록 위젯을 구성할 수 있습니다.
텍스트 및 조직 위젯:

대시보드에 이러한 위젯을 포함하려면 대시보드에 MosaicLayout이 있어야 합니다.
- CollapsibleGroup: 위젯 모음을 표시합니다. 그룹 보기를 접을 수 있습니다.
- SingleViewGroup: 위젯 모음에 하나의 위젯을 표시합니다. 표시할 위젯을 선택할 수 있습니다.
- SectionHeader: 대시보드에 가로 구분선을 만들고 대시보드의 목차에 항목을 만듭니다.
- Text: 텍스트 콘텐츠를 원시 텍스트 또는 마크다운 문자열로 표시합니다.

이 객체 외에도 대시보드에 빈 자리표시자를 추가할 수 있습니다.

예를 들어 다음은 오른쪽 Y축이 구성된 XyChart 위젯의 JSON 표현을 보여줍니다.

{
  "displayName": "Demo dashboard",
  "gridLayout": {
    "widgets": [
      {
        "title": "Sample line chart",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesFilter": {
                  "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
                  "aggregation": {
                    "perSeriesAligner": "ALIGN_MEAN",
                    "crossSeriesReducer": "REDUCE_MAX",
                    "groupByFields": [
                      "resource.label.zone"
                    ]
                  }
                },
                "unitOverride": "1"
              },
              "plotType": "LINE"
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

대시보드 필터

대시보드를 설계할 때는 대시보드에 표시되는 데이터를 보는 여러 방법을 식별할 수 있습니다. 예를 들어 대시보드에 가상 머신(VM) 인스턴스에 대한 측정항목이 표시되면 모든 VM에 대한 측정항목을 보고 특정 영역에 대한 측정항목을 볼 수 있습니다. 이 경우 영구 필터를 만들고 해당 필터의 기본값을 가장 일반적으로 사용되는 뷰로 설정하는 것이 좋습니다. 영구 필터는 일부 또는 모든 대시보드 위젯에 적용할 수 있습니다. Google Cloud 콘솔에서 대시보드를 볼 때 대시보드 툴바에는 영구 필터 및 필터 값을 일시적으로 변경하는 데 사용할 수 있는 메뉴가 표시됩니다.

영구 대시보드 필터에는 여러 가지 유형이 있습니다.

대시보드 전체 필터는 필터 라벨을 지원하고 해당 라벨의 값을 지정하지 않는 대시보드의 모든 위젯에 적용됩니다.

예를 들어 차트에 zone = us-central1-a 필터가 포함되어 있으면 해당 차트는 zone 라벨을 기반으로 대시보드 필터를 무시합니다. 마찬가지로 zone 라벨이 없는 차트는 이 라벨이 있는 대시보드 필터를 무시합니다.
템플릿 변수는 특정 위젯에 적용되는 이름이 지정된 변수입니다. 각 변수는 특정 라벨 및 값에 대한 것입니다. 템플릿 변수가 적용되는 위젯을 결정합니다.

모든 필터 유형은 동일한 데이터 구조로 표시됩니다. 자세한 내용은 DashboardFilter를 참조하세요.

예를 들어 다음은 템플릿 변수 및 대시보드 전체 필터를 정의하는 대시보드의 부분 JSON 표현을 보여줍니다.

{
  "dashboardFilters": [
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "templateVariable": "iid"
      },
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "zone"
      }
    ],
  "displayName": "Illustrate Template Variables",
  ...

표시된 JSON에서 dashboardFilters 구조의 첫 번째 항목은 이름이 iid인 템플릿 변수와 라벨 키 zone가 있는 대시보드 전체 필터에 대한 것입니다. 템플릿 변수는 instance_id 라벨의 별칭입니다.

템플릿 변수의 데이터 구조는 적용되는 위젯을 나열하지 않습니다. 대신 변수에 대한 참조를 포함하도록 위젯의 쿼리를 수정하여 위젯을 템플릿 변수와 연결합니다. 대시보드에 위젯이 표시되면 템플릿 변수 값이 확인됩니다.

로그 패널 및 차트에 주석을 추가하는 방법은 다음 섹션을 참조하세요.

로그 패널
MQL 정의 차트 및 테이블
PromQL 정의 차트 및 테이블
시계열 필터로 정의된 차트 및 테이블

로그 패널

템플릿 변수의 값에 따라 표시를 필터링하도록 로그 패널을 구성하려면 변수를 쿼리 창에 추가합니다. 다음 예시에서는 템플릿 변수 iid 값을 기준으로 필터링하는 쿼리를 보여줍니다.

${iid}

로그 패널에서 표시할 로그를 쿼리하기 전에 템플릿 변수가 확인됩니다. 이 예시에서 템플릿 변수 값이 "12345"이면 ${iid}는 resource.labels."instance_id"="12345" 문으로 대체됩니다.

쿼리에 템플릿 변수의 값만 포함할 수도 있습니다. 정규 표현식으로 정의된 필터의 일부로만 값을 사용하는 것이 좋습니다. 예를 들어 다음 쿼리는 정규 표현식을 사용하여 설명된 문자열이 포함된 JSON 페이로드가 있는 로그 항목과 일치시킵니다.

jsonPayload.message=~"Connected to instance: ${iid.value}"

로그 패널에 대한 쿼리를 구성한 다음 로그 탐색기를 여는 버튼을 선택하면 로그 탐색기가 열리기 전에 템플릿 변수가 확인됩니다.

다음 테이블에서는 로그 패널에서 템플릿 변수를 확인하는 방법을 보여줍니다.

구문	선택된 값	확인된 로그 패널 표현식
`${iid}`	`12345`	`resource.labels."instance_id"="12345"`
`${iid}`	`*`	`""`
`${iid.value}`	`12345`	`12345`
`${iid.value}`	`*`	`.*`

MQL 정의 차트 및 테이블

Monitoring 쿼리 언어(MQL)를 사용하여 차트를 구성할 때 쿼리 문자열에 파이프와 변수를 추가합니다.

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| every 1m
| ${iid}

차트에서 표시할 시계열을 쿼리하기 전에 템플릿 변수가 확인됩니다. 이 예시에서 템플릿 변수 값이 "12345"이면 ${iid}는 filter (resource.instance_id == '12345') 문으로 대체됩니다. 이 필터는 resource.instance_id 라벨이 있는 시계열과 일치하며 해당 라벨 값이 정확히 12345인 경우에만 일치합니다.

정규 표현식을 사용하여 시계열을 필터링하려면 템플릿 변수 값만 포함하도록 쿼리를 구성합니다. 구문을 설명하기 위해 다음은 정규 표현식을 사용하여 resource.instance_id 라벨 값에 템플릿 변수 iid 값이 포함되어 있는지 확인하는 방법을 보여줍니다.

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| filter resource.instance_id=~"${iid.value}"
| group_by 1m, [value_utilization_mean: mean(value.utilization)]
| every 1m

다음 표에서는 MQL 쿼리의 템플릿 변수가 확인되는 방법을 보여줍니다.

구문	선택된 값	확인된 MQL 표현식
`${iid}`	`12345`	`filter (resource.instance_id == '12345')`
`${iid}`	`*`	`filter (true)`
`${iid.value}`	`12345`	`12345`
`${iid.value}`	`*`	`.*`

PromQL 정의 차트 및 테이블

PromQL을 사용하여 차트를 정의할 때 중괄호로 묶인 변수를 쿼리 문자열에 추가합니다.

compute_googleapis_com:instance_cpu_utilization {
    project_id="my-project", ${iid}
}

차트에서 표시할 시계열을 쿼리하기 전에 템플릿 변수가 확인됩니다. 이 예시에서 템플릿 변수 값이 "12345"이면 ${iid}는 instance_id == '12345' 문으로 대체됩니다.

MQL과 마찬가지로 PromQL로 위젯을 정의할 때 쿼리는 템플릿 변수의 값만 추출할 수 있습니다. 정규 표현식으로 정의된 필터의 일부로만 값을 사용하는 것이 좋습니다. 구문을 설명하기 위해 다음은 정규 표현식을 사용하여 instance_id 라벨 값에 템플릿 변수 iid 값이 포함되어 있는지 확인하는 방법을 보여줍니다.

compute_googleapis_com:instance_cpu_utilization{
    instance_id=~"${iid.value}"
}

다음 표는 PromQL 쿼리의 템플릿 변수가 확인되는 방법을 보여줍니다.

구문	선택된 값	확인된 PromQL 표현식
`${iid}`	`12345`	`instance_id == '12345'`
`${iid}`	`*`	`noop_filter=~".*"`
`${iid.value}`	`12345`	`12345`
`${iid.value}`	`*`	`.+`

시계열 필터로 정의된 차트 및 테이블

시계열 필터를 사용하여 차트를 정의할 때 필터 문자열에 변수를 추가합니다.

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
           resource.type=\"gce_instance\" ${iid}"

MQL 및 PromQL 정의 차트와 달리 시계열 필터에서는 템플릿 변수 값을 사용할 수 없습니다.

다음 표에서는 템플릿 변수를 확인하는 방법을 보여줍니다.

구문	선택된 값	해결된 필터 표현식
`${iid}`	`12345`	`resource.instance_id == "12345"`
`${iid}`	`*`	중략
`${iid.value}`	`12345`	지원되지 않음
`${iid.value}`	`*`	지원되지 않음

대시보드 만들기

새 커스텀 대시보드를 만들려면 dashboards.create 메서드를 호출하고 대시보드에 표시할 레이아웃과 위젯을 제공합니다.

대시보드를 만들면 API가 dashboard_id를 자동으로 생성합니다. 커스텀 dashboard_id를 지정하려면 Dashboard 객체의 name 필드를 설정할 수 있습니다. 이름 필드의 형식은 다음과 같습니다.

"name": "projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}"

프로토콜

새 대시보드를 만들려면 POST 요청을 Dashboard 엔드포인트에 보냅니다.

curl -d @my-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X POST https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

프로젝트에서 대시보드를 만들려면 gcloud monitoring dashboards create 명령을 실행합니다.

gcloud monitoring dashboards create --config-from-file=my-dashboard.json

예를 들어 대시보드를 복제하려면 다음을 수행합니다.

대시보드 가져오기의 단계를 완료해서 원래 대시보드의 정의를 다운로드합니다.
반환된 JSON을 편집하여 etag 및 name 필드를 삭제하고 displayName 필드 값을 변경합니다.
명령어를 실행하여 대시보드를 만듭니다.

자세한 내용은 gcloud monitoring dashboards create 참조 문서를 확인하세요.

이 예에서는 my-dashboard.json 파일을 사용하여 샘플 대시보드를 만듭니다. Google Cloud 콘솔을 통해 대시보드를 관리할 수 있습니다.

추가 대시보드 구성은 예시 대시보드 및 레이아웃을 참조하세요.

대시보드 삭제

커스텀 대시보드를 삭제하려면 dashboards.delete 메서드를 호출하고 삭제할 대시보드를 지정합니다.

프로토콜

커스텀 대시보드를 삭제하려면 삭제할 대시보드의 ID로 Dashboard 엔드포인트에 DELETE 요청을 보냅니다.

curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

성공하면 메서드가 빈 응답을 반환합니다. 그렇지 않으면 오류가 반환됩니다.

gcloud

커스텀 대시보드를 삭제하려면 gcloud monitoring dashboards delete를 사용하고 삭제할 대시보드의 정규화된 ID를 지정합니다.

gcloud monitoring dashboards delete projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

자세한 내용은 gcloud monitoring dashboards delete 참조 문서를 확인하세요.

대시보드 나열

프로젝트에 속한 모든 커스텀 대시보드를 나열하려면 dashboards.list 메서드를 호출하고 프로젝트 ID를 지정합니다.

프로토콜

프로젝트의 모든 커스텀 대시보드를 나열하려면 프로젝트 ID를 Dashboard 엔드포인트로 보냅니다.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

프로젝트의 모든 커스텀 대시보드를 나열하려면 gcloud monitoring dashboards list 명령어를 사용합니다.

gcloud monitoring dashboards list

자세한 내용은 gcloud monitoring dashboards list 참조 문서를 확인하세요.

이 예시에서는 프로젝트와 연결된 커스텀 대시보드를 반환합니다.

list 응답을 페이지로 나누기

dashboards.list 메서드는 페이지 나누기를 지원하므로 한 번에 한 페이지씩 결과를 가져올 수 있습니다.

프로토콜

결과 목록의 첫 페이지에 요청과 함께 pageSize 쿼리 매개변수를 지정합니다.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards?page_size=1

이 메서드는 목록의 첫 페이지와 nextPageToken을 반환합니다. 예를 들면 다음과 같습니다.

{
  "dashboards" : [
    {
       "displayName" : "Grid Layout Example",
       "gridLayout" : {
         "widgets" : [
            { ... },
            { ... },
            { ... },
          ]
       }
    }
  ]
},
"nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"

나머지 각 페이지의 경우 요청에 해당 nextPageToken을 포함해야 합니다.

gcloud

페이지당 리소스 수를 지정하려면 명령어로 --page-size 플래그를 사용합니다. 예를 들면 다음과 같습니다.

gcloud monitoring dashboards list --page-size=1

대시보드 가져오기

프로젝트의 특정 커스텀 대시보드를 가져오려면 대시보드 ID로 정규화된 dashboards.get 메서드를 호출합니다.

프로토콜

특정 커스텀 대시보드를 가져오려면 대시보드 ID를 Dashboard 엔드포인트로 보냅니다.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

이 메서드는 다음 예시와 비슷한 응답을 반환합니다.

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

gcloud

특정 커스텀 대시보드를 가져오려면 gcloud monitoring dashboards describe 명령어를 사용하고 대시보드 ID를 지정합니다.

gcloud monitoring dashboards describe ${DASHBOARD_ID} --format=json

이 명령어는 요청된 대시보드를 반환합니다.

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

자세한 내용은 gcloud monitoring dashboards describe 참조 문서를 확인하세요.

대시보드 업데이트

기존 커스텀 대시보드를 업데이트하려면 dashboards.patch 메서드를 호출합니다. 현재 etag 값을 가져오려면 dashboards.get 메서드를 호출하여 응답에서 찾을 수 있습니다.

프로토콜

커스텀 대시보드를 업데이트하려면 Dashboard 엔드포인트에 PATCH 요청을 보내고 최신 dashboards.get 응답에서 수정된 Dashboard 객체와 etag 값을 제공합니다.

curl -d @my-updated-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X PATCH https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

gcloud

커스텀 대시보드를 업데이트하려면 gcloud monitoring dashboards update를 사용하고, 업데이트할 대시보드의 ID를 지정하고, 대시보드에 변경 사항을 제공합니다.

gcloud monitoring dashboards update ${DASHBOARD_ID} --config-from-file=my-updated-dashboard.json

자세한 내용은 gcloud monitoring dashboards update 참조 문서를 확인하세요.

이 예시에서는 my-updated-dashboard.json 파일을 사용하여 기존 커스텀 대시보드를 업데이트하고 업데이트된 대시보드 목록의 복사본을 반환합니다. 반환 데이터에는 새로운 etag 값이 포함됩니다.

API로 대시보드 만들기 및 관리

시작하기 전에

대시보드 레이아웃

대시보드 위젯

대시보드 필터

로그 패널

MQL 정의 차트 및 테이블

PromQL 정의 차트 및 테이블

시계열 필터로 정의된 차트 및 테이블

대시보드 만들기

프로토콜

gcloud

대시보드 삭제

프로토콜

gcloud

대시보드 나열

프로토콜

gcloud

list 응답을 페이지로 나누기

프로토콜

gcloud

대시보드 가져오기

프로토콜

gcloud

대시보드 업데이트

프로토콜

gcloud

다음 단계