API를 통한 대시보드 관리

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

이 페이지에서는 Cloud Monitoring API에서 Dashboard 리소스를 사용하여 커스텀 대시보드와 해당 대시보드의 위젯을 관리하는 방법을 설명합니다. Google Cloud Console을 통해 커스텀 대시보드를 관리할 수도 있지만 API를 사용하면 수많은 대시보드를 프로그래매틱 방식으로 동시에 관리할 수 있습니다. 또한 Cloud Monitoring API를 사용하여 대시보드 위젯을 만들고, 구성하고, 조작할 수 있습니다.

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

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

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축을 사용하여 데이터를 표시합니다. Google Cloud Console을 통해 생성된 선 차트, 막대 차트, 누적 영역 차트, 히트맵 차트는 이 위젯의 인스턴스입니다. 선 차트, 누적 막대 그래프, 누적 영역 차트를 만드는 경우 측정항목이 왼쪽 또는 오른쪽 Y축을 참조하도록 지정할 수 있습니다. 여러 측정항목을 차트로 표시할 때 Y축을 모두 사용할 수 있습니다.

    SLO 차트도 XyChart 위젯의 인스턴스이지만 API를 사용해서는 SLO 차트를 만들 수 없습니다.

  • AlertChart: 단일 조건 알림 정책의 요약을 표시합니다. 이 위젯은 데이터를 선 차트로 표시하고, 임곗값을 표시하고, 열린 이슈 수를 나열합니다.

  • CollapsibleGroup: 위젯 모음을 표시합니다. 그룹 보기를 접을 수 있습니다. 대시보드에 이러한 위젯을 포함하려면 대시보드에 MosaicLayout이 있어야 합니다.

  • LogsPanel: 현재 Google Cloud 프로젝트에 저장된 프로젝트 범위 로그 항목을 표시합니다. 현재 측정항목 범위를 통해 액세스할 수 있는 Cloud 프로젝트에 저장된 로그 항목을 표시하도록 위젯을 구성할 수 있습니다.

  • Scorecard: 측정항목의 최신 값과 이 값이 하나 이상의 기준과 관련되는 방식을 표시합니다.

  • TimeSeriesTable: 측정항목의 최신 값을 표시합니다. 열을 기준으로 테이블을 정렬하고, 테이블을 필터링하고, 디스플레이에서 열을 추가하거나 삭제할 수 있습니다.

  • 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 Console에서 대시보드를 볼 때 대시보드 툴바에는 영구 필터 및 필터 값을 일시적으로 변경하는 데 사용할 수 있는 메뉴가 표시됩니다.

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

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

    예를 들어 차트에 zone = us-central1-a 필터가 포함되어 있으면 해당 차트는 zone 라벨을 기반으로 대시보드 필터를 무시합니다. 마찬가지로 zone 라벨이 없는 차트는 이 라벨이 있는 대시보드 필터를 무시합니다.

  • 템플릿 변수는 특정 위젯에 적용되는 이름이 지정된 변수입니다. 각 변수는 특정 라벨 및 값에 대한 것입니다. 템플릿 변수가 적용되는 위젯을 결정합니다.

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

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

{
  "category": "CUSTOM",
  "dashboardFilters": [
    {
      "filterType": "RESOURCE_LABEL",
      "labelKey": "zone",
      "stringValue": "us-central1-b",
      "templateVariable": "my_zone_temp_var"
    },
    {
      "filterType": "RESOURCE_LABEL",
      "labelKey": "project_id",
      "stringValue": "my-project-id",
      "templateVariable": ""
    }
  ],
  "displayName": "Illustrate Template Variables",
  ...

표시된 JSON에서 dashboardFilters 구조의 첫 번째 항목은 이름이 my_zone_temp_var인 템플릿 변수에 대한 것입니다. 두 번째 항목은 대시보드 전체 필터에 대한 것입니다. 모든 대시보드 위젯에 적용되는 이러한 필터의 경우 templateVariable 필드 값은 길이가 0인 문자열 ""로 설정됩니다.

템플릿 변수의 데이터 구조는 적용되는 위젯을 나열하지 않습니다. 대신 위젯을 템플릿 변수와 연결하면 위젯의 쿼리가 변수에 대한 참조를 포함하도록 수정됩니다. Monitoring 쿼리 언어(MQL)를 사용하여 차트를 구성할 때 쿼리 문자열에 파이프와 변수를 추가합니다.


"timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization\n|
           every 1m\n| ${my_zone_temp_var}\n"

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

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

다음 JSON은 차트의 전체 정의 맥락에서 쿼리 문자열을 보여줍니다.

{
  ...
  "displayName": "Illustrate Template Variables",
  "mosaicLayout": {
    "columns": 12,
    "tiles": [
      {
        "height": 4,
        "widget": {
          "title": "MQL",
          "xyChart": {
            "chartOptions": {
              "mode": "COLOR"
            },
            "dataSets": [
              {
                "plotType": "LINE",
                "targetAxis": "Y1",
                "timeSeriesQuery": {
                  "timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization\n| every 1m\n| ${my_zone_temp_var} \n"
                }
              }
            ],
            "timeshiftDuration": "0s",
            "yAxis": {
              "label": "y1Axis",
              "scale": "LINEAR"
            }
          }
        },
        "width": 6,
        "xPos": 0,
        "yPos": 0
      },
      {
        "height": 4,
        "widget": {
          "title": "LTS",
          "xyChart": {
            "chartOptions": {
              "mode": "COLOR"
            },
            "dataSets": [
              {
                "minAlignmentPeriod": "60s",
                "plotType": "LINE",
                "targetAxis": "Y1",
                "timeSeriesQuery": {
                  "apiSource": "DEFAULT_CLOUD",
                  "timeSeriesFilter": {
                    "aggregation": {
                      "alignmentPeriod": "60s",
                      "crossSeriesReducer": "REDUCE_NONE",
                      "perSeriesAligner": "ALIGN_MEAN"
                    },
                    "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\" ${my_zone_temp_var}"
                  }
                }
              }
            ],
            "timeshiftDuration": "0s",
            "yAxis": {
              "label": "y1Axis",
              "scale": "LINEAR"
            }
          }
        },
        "width": 6,
        "xPos": 6,
        "yPos": 0
      }
    ]
  }
}

표시할 데이터 지정

시계열에서 검색된 데이터를 표시하는 모든 위젯에는 그 안에 TimeSeriesQuery 객체가 포함되어 있습니다. 이 객체는 위젯에 사용할 시계열 데이터를 지정합니다.

다음과 같이 표시할 시계열 데이터를 지정할 수 있습니다.

Google Cloud Console을 통해 대시보드 위젯을 만든 경우 사용자가 측정항목 및 시계열에 익숙할 것입니다.

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

다음 가이드도 유용할 수 있습니다.

이 가이드는 Google Cloud 콘솔을 사용하여 대시보드를 만들 수 있도록 작성되었지만 Cloud Monitoring API를 사용하여 위젯을 만드는 경우에도 이 개념이 적용됩니다.

curl 사용 예시

이 섹션에서는 curl 도구를 사용하여 Cloud Monitoring API를 호출하는 데 사용되는 규칙과 설정을 설명합니다. 이 페이지의 예시에서는 curl 도구를 사용하여 REST 엔드포인트로 HTTP 요청을 전송하여 API에 액세스합니다. 호출 예시에 사용된 변수를 설정하려면 다음 정보를 사용하세요.

인증

  1. Cloud 프로젝트의 ID를 저장할 환경 변수를 만듭니다. 다음 예시에서는 PROJECT_ID를 사용합니다.

    PROJECT_ID=a-gcp-project-12345
    
  2. Google Cloud CLI에 인증합니다.

    gcloud auth login
    
  3. 원하는 경우 gcloud CLI를 사용하여 프로젝트 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....
    
  6. 대시보드의 ID를 저장할 환경 변수를 만듭니다. 이 예시에서는 DASHBOARD_ID 변수를 사용합니다.

curl 호출

curl 호출에는 인수 집합과 리소스의 URL이 포함됩니다. 일반적인 인수에는 PROJECT_ID, DASHBOARD_ID, ACCESS_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/${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

자세한 내용은 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/${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 값이 포함됩니다.