이 문서에서는 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축에 데이터를 표시합니다.이 위젯은 시계열 데이터이거나 SQL 쿼리로 생성될 수 있는 데이터 세트를 표시합니다. 이 위젯을 사용하면 차트 데이터를 왼쪽 또는 오른쪽 Y축과 연결할 수 있습니다. 여러 측정항목 유형을 차트로 표시할 때 Y축을 모두 사용할 수 있습니다.
XyChart
위젯은 다음 표시 스타일을 지원합니다.- 선 차트
- 막대 그래프
- 누적 영역 차트
- 히트맵
하나의 측정기준에서 표시되는 위젯(예: 최신 값)은 다음과 같습니다.
PieChart
: 시계열 모음의 최신 값을 표시하며, 각 시계열은 원형 차트의 한 조각에 해당합니다.Scorecard
: 시계열의 최신 값과 이 값이 하나 이상의 기준과 관련되는 방식을 표시합니다.TimeSeriesTable
: 각 시계열의 최신 값 또는 집계된 값을 표시합니다. 테이블은 맞춤설정을 지원합니다. 예를 들어 셀을 색상으로 분류하고 열 이름 및 데이터 정렬을 구성할 수 있습니다.
알림 정책 또는 이슈 정보를 표시하는 위젯:
AlertChart
: 단일 조건 알림 정책의 요약을 표시합니다. 이 위젯은 데이터를 선 차트로 표시하고, 기준점을 표시하고, 열린 이슈 수를 나열합니다.IncidentList
: 이슈 목록을 표시합니다. 특정 알림 정책 또는 특정 리소스 유형에 대한 이슈를 표시하도록 위젯을 구성할 수 있습니다.
로그 항목 및 오류를 표시하는 위젯:
ErrorReportingPanel
: 선택한 Google Cloud 프로젝트에 저장된 오류 그룹을 표시합니다.LogsPanel
: 현재 Google Cloud 프로젝트에 저장된 프로젝트 범위 로그 항목을 표시합니다. 현재 측정항목 범위를 통해 액세스할 수 있는 Google Cloud 프로젝트에 저장된 로그 항목을 표시하도록 위젯을 구성할 수 있습니다.
텍스트 및 조직 위젯:
CollapsibleGroup
: 위젯 모음을 표시합니다. 그룹 보기를 접을 수 있습니다.SingleViewGroup
: 위젯 모음에 하나의 위젯을 표시합니다. 표시할 위젯을 선택할 수 있습니다.SectionHeader
: 대시보드에 가로 구분선을 만들고 대시보드의 목차에 항목을 만듭니다.Text
: 텍스트 콘텐츠를 원시 텍스트 또는 마크다운 문자열로 표시합니다.
대시보드에 텍스트 및 조직 위젯을 포함하려면 대시보드에
MosaicLayout
이 있어야 합니다.
이 객체 외에도 대시보드에 빈 자리표시자를 추가할 수 있습니다.
예를 들어 다음은 오른쪽 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"
}
}
}
]
}
}
대시보드 라벨
라벨은 대시보드를 관리하고 정리하는 데 도움이 됩니다. 예를 들어 프로덕션 리소스에 대한 시계열 데이터 및 로그 데이터를 대시보드에 표시하기 위해 prod
라는 레이블을 추가할 수 있습니다. 또는 playbook
라벨을 추가하여 대시보드에 오류 문제 해결에 도움이 되는 정보가 포함되어 있음을 나타낼 수 있습니다.
대시보드에 라벨 추가는 선택사항입니다.
예를 들어 다음은 playbook
이라는 라벨을 지정하는 Dashboard
객체를 보여줍니다.
{
"displayName": "Example",
"mosaicLayout": {
"columns": 12,
"tiles": [
...
]
},
"dashboardFilters": [],
"labels": {
"playbook": ""
}
}
이전 샘플에서 알 수 있듯이 labels
필드는 map
으로 구현되며, 여기서 key
필드와 value
필드는 모두 문자열입니다. 대시보드에 라벨을 추가할 때 key
를 라벨 이름으로 설정하고 value
필드를 빈 문자열로 설정합니다.
대시보드 필터
대시보드를 설계할 때는 대시보드에 표시되는 데이터를 보는 여러 방법을 식별할 수 있습니다. 예를 들어 대시보드에 가상 머신(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
의 별칭입니다.
템플릿 변수의 데이터 구조는 적용되는 위젯을 나열하지 않습니다. 대신 변수 참조를 포함하도록 위젯의 쿼리를 수정하여 위젯을 템플릿 변수와 연결합니다. 대시보드에 위젯이 표시되면 템플릿 변수 값이 확인됩니다.
로그 패널과 차트에 주석을 추가하는 방법은 다음 섹션을 참조하세요.
로그 패널
템플릿 변수 값에 따라 표시를 필터링하도록 로그 패널을 구성하려면 쿼리 창에 변수를 추가합니다. 다음 예시는 템플릿 변수 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
값이 포함됩니다.