API를 통한 대시보드 관리

Cloud Monitoring API의 Dashboard 리소스를 사용하여 대시보드와 차트를 관리할 수 있습니다. 엔드포인트는 대시보드를 관리하고 구성하기 위해 다음 메서드를 지원합니다.

curl 유틸리티를 사용하거나 gcloud 명령줄 도구를 사용하여 API를 직접 호출할 수 있습니다.

또한 Google Cloud Console을 통해 대시보드를 관리할 수 있지만 API를 사용하면 많은 대시보드를 동시에 프로그래매틱 방식으로 관리할 수 있습니다. 또한 차트는 대시보드에서 위젯으로 구현되므로 대시보드 API를 사용하여 차트를 만들고 구성하고 조작할 수도 있습니다.

시작하기 전에

대시보드를 만들 때는 표시할 구성요소 또는 위젯과 해당 위젯의 레이아웃을 지정해야 합니다.

대시보드 레이아웃 정의

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

  • GridLayout: 사용 가능한 공간을 동일한 너비의 수직 열로 나누고 행 우선 전략을 사용하여 위젯 집합을 정렬합니다.

  • 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축을 사용하여 데이터를 표시합니다. Google Cloud Console을 통해 만든 차트는 이 위젯의 인스턴스입니다.

  • Scorecard: 측정항목의 최신 값과 이 값이 하나 이상의 기준과 관련되는 방식을 표시합니다. 이 위젯은 API를 사용해서만 만들 수 있습니다.

  • Text: 텍스트 콘텐츠를 원시 텍스트 또는 마크다운 문자열로 표시합니다. API를 사용해서만 이 위젯을 만들 수 있습니다.

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

예를 들어 다음은 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"
              }
            }
          }
        ]
      }
    }
    

표시할 데이터 지정

Google Cloud Console을 통해 차트를 만든 경우 이미 측정항목과 시계열에 익숙합니다. XyChart 외에도 대시보드 API를 사용하여 추가 위젯을 통해 데이터를 시각화할 수 있습니다.

측정항목 및 시계열에 대한 자세한 내용은 측정항목, 시계열 및 리소스를 참조하세요.

또한 차트 만들기, 측정항목 선택, 보기 옵션 설정 가이드가 도움이 될 수 있습니다. 이 가이드는 Google Cloud Console을 통해 차트를 만드는 용도로 작성되었지만, 대시보드 API를 사용하여 차트를 만드는 데는 차트를 만들고, 측정항목을 선택하고 보기 옵션을 선택하는 개념도 적용됩니다.

curl 사용 예시

이 섹션에서는 curl 도구를 사용하여 Dashboard API를 호출하는 데 사용되는 규칙 및 설정에 대해 설명합니다. 이 페이지의 예에서는 curl 도구를 사용하여 REST 엔드포인트로 HTTP 요청을 보냅니다. 인증 및 curl 호출에 대한 다음 정보를 사용하여 호출 예시에 사용된 변수를 설정합니다.

인증

  1. Cloud Monitoring 작업공간의 ID를 저장할 환경 변수를 만듭니다. 다음 예에서는 PROJECT_ID를 사용합니다.

        PROJECT_ID=a-gcp-project-12345
        
  2. Cloud SDK에 인증:

    gcloud auth login
        
  3. 원하는 경우 Cloud SDK를 사용하여 프로젝트 ID를 기본값으로 설정해서 각 명령어로 지정하지 않아도 됩니다.

    gcloud config set project ${PROJECT_ID}
        
  4. 인증 토큰을 만들고 환경 변수에 저장합니다. 이 예에서는 변수 ACCESS_TOKEN를 호출합니다.

    ACCESS_TOKEN=`gcloud auth print-access-token`
        

    정기적으로 액세스 토큰을 새로고침해야 합니다. 작업한 명령어에서 사용자가 인증되지 않았다고 갑자기 보고하면 이 명령어를 다시 실행합니다.

  5. 액세스 토큰을 받았는지 확인하려면 ACCESS_TOKEN 변수를 출력합니다.

    echo ${ACCESS_TOKEN}
        ya29.ImW8Bz56I04cN4qj6LF....
        

curl 호출

curl 호출에는 여러 인수와 대시보드 API 리소스의 URL이 포함됩니다. 일반적인 인수에는 PROJECT_IDACCESS_TOKEN 환경 변수로 지정된 값이 포함됩니다. 예를 들어 HTTP 요청의 유형을 지정하기 위해 다른 인수를 지정해야 할 수도 있습니다(예: -X DELETE).

curl 호출은 다음과 같은 일반적인 구조를 취합니다.

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

예를 들어 프로젝트의 모든 대시보드를 나열하기 위해 다음 요청을 실행합니다.

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

이 요청은 프로젝트와 연결된 대시보드 목록을 반환합니다.

{
      "dashboards": [
        {
          "name": "projects/123456789000/dashboards/c2ab1f1c-b8b9-1234-9c48-c7745802b659",
          "displayName": "Grid-layout example",
          "etag": "76a95cc500a7c7d6b3799709c13afe91",
          "gridLayout": {
            "widgets": [
              {
                "text": {
                  "content": "Text Widget 1",
                  "format": "RAW"
                }
              },
              {
                "text": {
                  "content": "**Text Widget 2**",
                  "format": "MARKDOWN"
                }
              },
              {
                "text": {
                  "content": "_Text Widget 3_",
                  "format": "MARKDOWN"
                }
              }
            ]
          }
        },
        {
          "name": "projects/123456789000/dashboards/cae85db7-6920-4e67-a45c-97a94c0e2679",
          "displayName": "Row-layout example",
          "etag": "a600be01afe0b37762cd7a9b92fc3e7e",
          "rowLayout": {
            "rows": [
              {
                "widgets": [
                  {
                    "text": {
                      "content": "Text Widget 1",
                      "format": "RAW"
                    }
                  },
                  {
                    "text": {
                      "content": "**Text Widget 2**",
                      "format": "MARKDOWN"
                    }
                  },
                  {
                    "text": {
                      "content": "_Text Widget 3_",
                      "format": "MARKDOWN"
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
    

대시보드 만들기

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

대시보드를 만들 때 API는 자동으로 dashboard_id를 호출합니다. 커스텀 dashboard_id를 지정하려면 Dashboard 객체의 name 필드를 설정하면 됩니다. 이름 필드의 형식은 다음과 같습니다.

    "name": "projects/[HOST_PROJECT_ID]/dashboards/[DASHBOARD_ID]"
    

API에서 [HOST_PROJECT_ID]는 작업공간의 호스트 프로젝트여야 합니다. 작업공간과 연결되지 않거나 작업공간의 호스트 프로젝트가 아닌 Google Cloud 프로젝트 식별자를 지정하면 400 오류가 발생합니다. 작업공간을 만들고 관리하는 방법에 대한 자세한 내용은 작업공간을 참조하세요.

프로토콜

새 대시보드를 만들려면 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
    

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

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

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

대시보드 삭제

대시보드를 삭제하려면 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/[MY_PROJECT_ID]/dashboards/[MY_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 참조 문서를 확인하세요.

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

목록 응답을 페이지로 나누기

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 메서드를 호출하여 응답에서 찾을 수 있습니다.

프로토콜

대시보드를 업데이트하려면 PATCH 요청을 Dashboard 엔드포인트에 보내고 가장 최근의 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 값을 포함하여 업데이트된 대시보드 목록의 사본을 반환합니다.