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축에 데이터를 표시합니다.

  이 위젯은 시계열 데이터이거나 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 필드를 빈 문자열로 설정합니다.

참고: Dashboard.labels 객체에서는 key 필드만 처리됩니다. value 필드는 무시됩니다.

대시보드 필터 및 변수

대시보드를 설계할 때는 대시보드에 표시되는 데이터를 보는 여러 방법을 식별할 수 있습니다. 예를 들어 대시보드에 가상 머신(VM) 인스턴스에 대한 시계열 데이터가 표시된다고 가정해 보겠습니다. 모든 VM에 대한 시계열 데이터를 보려할 수도 있고, 특정 영역에 있는 데이터만 보려할 수도 있습니다. 이 경우 고정된 필터 또는 변수를 만든 다음 해당 필터의 기본값을 가장 자주 조회되는 영역으로 설정하는 것이 좋습니다.

고정된 필터는 위젯에 동일한 라벨 키가 있는 필터가 포함되어 있지 않는 한 필터에 지정된 라벨을 지원하는 모든 대시보드 위젯에 적용됩니다. 예를 들어 차트에 zone = us-central1-a 필터가 포함되어 있으면 해당 차트는 라벨 키가 zone인 고정된 필터를 무시합니다. 마찬가지로 zone 키가 있는 라벨이 없는 차트에서는 이 필터가 무시됩니다.

변수는 고정된 필터와 비슷하지만 특정 위젯에만 적용됩니다. 고정된 필터와 같이 라벨을 기반으로 할 수도 있고 값만 보유할 수도 있습니다. 값 전용 변수에는 하나 이상의 기본값과 가능한 모든 값의 목록이 포함됩니다. 기본값을 지정하지 않으면 기본값은 와일드 카드 연산자 (*)로 설정됩니다. 가능한 모든 값의 집합을 정의하려면 값 배열을 제공하거나 SQL 쿼리를 작성합니다.

고정된 필터와 변수 모두 대시보드 툴바에 각 변수와 변수 값을 일시적으로 변경할 수 있는 메뉴가 표시됩니다. 고정된 필터와 변수를 나타내는 데도 동일한 데이터 구조가 사용됩니다. 자세한 내용은 DashboardFilter를 참조하세요.

라벨 기반 변수 또는 값 전용 변수를 위젯에 적용하는 방법을 알아보려면 다음 섹션을 참고하세요.

• 변수 역참조의 일반적인 문법
• 로그 패널 위젯
• PromQL 쿼리가 포함된 차트
• SQL 쿼리가 포함된 차트
• MQL 쿼리가 포함된 차트

• Monitoring 필터 쿼리가 포함된 차트

  메뉴 기반 인터페이스를 사용하여 시계열 데이터를 표시하는 차트를 만들면 선택 항목이 Monitoring 필터로 변환됩니다.

필터 및 변수 만들기

콘솔

Google Cloud 콘솔을 사용하여 고정된 필터와 변수를 만드는 방법에 관한 자세한 내용은 다음 문서를 참고하세요.

• 필터 만들기 및 고정하기
• 변수 만들기

API

고정된 필터와 변수를 정의하려면 dashboardFilters 데이터 구조를 사용하세요.

• 변수를 만들려면 templateVariable 필드의 값을 변수 이름으로 설정합니다. 고정된 필터를 만들려면 이 필드를 생략하거나 값을 빈 문자열로 설정합니다.
• 고정된 필터 또는 라벨 기반 변수를 만들려면 labelKey 필드를 지정해야 합니다. 값 전용 변수를 사용하려면 이 필드를 생략합니다.

• 필터 또는 변수의 기본값을 설정합니다. 이 필드의 구성에 따라 사용자가 값 메뉴에서 옵션을 하나만 선택할 수 있는지 또는 여러 값을 선택할 수 있는지가 결정됩니다.

  • 단일 기본값을 설정하고 사용자가 값 메뉴에서 정확히 하나의 옵션만 선택하도록 제한하려면 valueType 필드를 STRING로 설정하고 stringValue 필드도 설정합니다.

  "valueType": "STRING",
  "stringValue": "my-default-value",
  

  • 기본값을 하나 이상 설정하고 사용자가 값 메뉴에서 여러 옵션을 선택할 수 있도록 하려면 valueType 필드를 STRING_ARRAY로 설정하고 stringArrayValue 필드도 설정합니다. 다음 예시에는 세 가지 기본값이 있습니다.

  "valueType": "STRING_ARRAY",
  "stringArrayValue": {
    "values": [ "a", "b", "c" ]
  },
  

  참고: 기본값을 지정하지 않으면 와일드 카드 연산자 (*)가 자동으로 선택됩니다. 로그 패널에서 변수를 사용하려면 정규 표현식을 비교자로 사용해야 합니다. SQL 쿼리의 경우 IF 문을 사용해야 합니다. 자세한 내용은 SQL 쿼리가 포함된 차트를 참고하세요.

• 선택사항: 값 전용 변수의 가능한 모든 값 목록을 지정하려면 stringArray 필드 또는 timeSeriesQuery 필드를 설정하세요. 쿼리를 지정하는 경우 분석 쿼리여야 합니다.

  참고: 고정된 필터 또는 라벨 기반 변수를 만들 때는 timeSeriesQuery 또는 stringArray 필드를 설정하지 마세요. 가능한 모든 값 집합은 동적으로 결정됩니다.

예를 들어 다음 dashboardFilters 객체를 고려해 보세요.

{
  "dashboardFilters": [
      {
        "labelKey": "zone"
        "stringValue": "us-central1-c",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL"
      },
      {
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL",
        "templateVariable": "my_label_based_variable"
      },
      {
        "filterType": "VALUE_ONLY",
        "templateVariable": "my_value_only_variable",
        timeSeriesQuery: {
          opsAnalyticsQuery: {
            sql: "
              SELECT log_name
              FROM `MY_TABLE`
              GROUP BY log_name
            ",
          }
        }
      }
    ],
  "displayName": "Illustrate Variables",
  ...
}

이전 JSON은 고정된 필터 1개와 변수 2개를 정의합니다.

• 고정된 필터의 라벨 키는 zone이며 툴바에 표시됩니다. valueType 및 stringValue 필드는 단일 기본값을 지정합니다. 자세한 내용은 dashboardFilters 데이터 구조의 API 참조 페이지를 참고하세요.

• 라벨 기반 변수의 이름은 my_label_based_variable이고 라벨 키는 instance_id입니다. 이 변수의 기본값은 특정 인스턴스 ID로 설정됩니다. 배열을 사용하여 기본값을 구성할 수도 있습니다. 툴바에 my_label_based_variable이라는 이름으로 필터가 표시됩니다.

• 값 전용 변수의 이름은 my_value_only_variable입니다. 이 항목에는 기본값이 지정되어 있지 않으므로 와일드 카드 연산자 (*)가 자동으로 적용됩니다. 또한 이 변수는 SQL 쿼리를 사용하여 변수의 가능한 값 목록을 생성합니다.

dashboardFilters 객체는 변수가 적용되는 위젯을 나열하지 않습니다. 위젯에 변수를 적용하려면 위젯의 쿼리를 수정합니다.

변수 역참조를 위한 일반적인 문법

SQL로 정의된 위젯을 제외한 모든 위젯의 경우 다음 구문을 사용하여 쿼리에 변수를 적용합니다.

• 라벨 기반 변수를 적용하고 라벨 키와 라벨 값을 쿼리 언어의 유효한 필터 표현식으로 확인하려면 ${my_label_based_variable}를 사용하세요.

• 라벨 기반 변수의 값만 적용하려면 ${my_label_based_variable.value}를 사용합니다. 비교에는 정규 표현식을 사용해야 합니다.

• 값 전용 변수의 값만 적용하려면 ${my_value_only_variable}를 사용하세요. 값 전용 변수의 경우 .value 절을 포함하지 않습니다. 비교에는 정규 표현식을 사용해야 합니다.

로그 패널 위젯

로그 패널 위젯에 변수를 적용하려면 쿼리 창을 업데이트합니다. 이러한 위젯의 문법은 일반 문법에 지정된 문법을 따릅니다.

콘솔

예를 들어 다음 쿼리는 정규 표현식을 사용하여 jsonPayload.message 필드의 값을 라벨 기반 변수의 값이 포함된 문자열 값과 비교합니다.

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

다른 예로 값 전용 변수 value_only_severity_variable를 생각해 보겠습니다. 값 메뉴에서 ERROR, INFO, NOTICE의 세 가지 값이 선택되었다고 가정해 보겠습니다. 다음으로 로그 패널 위젯의 쿼리 창에 다음을 추가합니다.

severity =~ "${value_only_severity_variable}"

다음은 렌더링된 양식을 보여줍니다.

severity =~ "^(ERROR|INFO|NOTICE)$"

API

예를 들어 다음 JSON은 로그 패널 위젯의 쿼리에 라벨 기반 변수를 적용하는 방법을 보여줍니다.

"logsPanel": {
  "filter": "${my_label_based_variable}",
  "resourceNames": [
    "projects/1234512345"
  ]
},

예를 들어 다음 쿼리는 정규 표현식을 사용하여 jsonPayload.message 필드의 값을 라벨 기반 변수의 값이 포함된 문자열 값과 비교합니다.

"logsPanel": {
  "filter": "resource.type=\"gce_instance\"\n
             resource.labels.project_id=~\"${my_label_based_variable.value}\"\n",
  "resourceNames": [
    "projects/012345"
  ]
}

다른 예로 값 전용 변수 value_only_severity_variable를 고려하고 메뉴에서 ERROR, INFO, NOTICE의 세 가지 값이 선택되었다고 가정해 보겠습니다. 다음으로 로그 패널 위젯의 쿼리 창에 다음을 추가합니다.

"logsPanel": {
  "filter": "severity =~ \"${value_only_severity_variable}\"\n",
  ...
}

다음은 로그 패널 위젯에서 실행된 쿼리를 보여줍니다.

severity =~ "^(ERROR|INFO|NOTICE)$"

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

다음 표는 로그 패널에서 예시 변수를 확인하는 방법을 보여줍니다. 앞에서 언급했듯이 변수의 값만 사용되는 경우 정규 표현식을 비교 연산자로 사용해야 합니다.

구문	선택된 값	확인된 로그 패널 표현식
${my_label_based_variable}	12345	resource.labels."instance_id"="12345" 예시 변수는 리소스 라벨 instance_id을 기반으로 합니다.
${my_label_based_variable}	*	""
${my_label_based_variable.value} ${my_value_based_variable}	12345	12345
${my_label_based_variable.value} ${my_value_based_variable}	*	.*

PromQL 쿼리가 포함된 차트

PromQL 쿼리가 있는 차트에 라벨 기반 변수를 적용하려면 일반 문법에 나와 있는 안내를 따르세요.

콘솔

예를 들어 다음 쿼리는 라벨 기반 변수 my_label_based_variable가 필터 표현식으로 확인되는 것을 사용합니다.

compute_googleapis_com:instance_cpu_utilization{
    monitored_resource="gce_instance", ${my_label_based_variable} }

쿼리를 수정하여 변수의 값만 확인할 수도 있습니다. 다음 예에서는 정규 표현식을 사용하여 라벨 기반 쿼리의 값을 instance_id와 비교합니다.

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

값 전용 변수가 있는 경우 .value 절을 생략합니다. 예를 들어 값 전용 변수를 사용하여 영역별로 필터링하려면 쿼리에 다음과 같은 내용이 포함됩니다.

zone=~"${my_value_only_variable}"

API

예를 들어 다음 JSON은 라벨 기반 변수 my_label_based_variable가 필터 표현식으로 확인되는 것을 사용하는 쿼리를 보여줍니다.

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
      monitored_resource=\"gce_instance\",
      ${my_label_based_variable}
      }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

쿼리를 수정하여 변수의 값만 확인할 수도 있습니다. 다음 예에서는 정규 표현식을 사용하여 라벨 기반 쿼리의 값을 instance_id와 비교합니다.

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
    monitored_resource=\"gce_instance\",
    instance_id=~\"${my_label_based_variable.value}\"
    }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

값 전용 변수가 있는 경우 .value 절을 생략합니다. 예를 들어 값 전용 변수를 사용하여 영역별로 필터링하려면 쿼리에 다음과 같은 내용이 포함됩니다.

zone=~\"${my_value_only_variable}\"

다음 표는 예시 변수가 PromQL에 의해 확인되는 방식을 보여줍니다. 앞에서 언급했듯이 변수의 값만 사용되는 경우 정규 표현식을 비교 연산자로 사용해야 합니다.

구문	선택된 값	확인된 PromQL 표현식
${my_label_based_variable}	12345	instance_id == '12345' 예시 변수는 리소스 라벨 instance_id을 기반으로 합니다.
${my_label_based_variable}	*	noop_filter=~".*"
${my_label_based_variable.value} ${my_value_based_variable}	12345	12345
${my_label_based_variable.value} ${my_value_based_variable}	*	.+

SQL 쿼리가 포함된 차트

SQL 정의 위젯에 변수를 적용하려면 WHERE 절을 업데이트하여 변수의 값을 참조합니다. 모든 변수의 경우 변수 이름 앞에 'at' 기호를 붙입니다(예: @variable_name). 라벨 기반 변수의 경우 변수 이름 @my_label_based_variabe.value에 .value를 추가합니다.

SQL 쿼리의 경우 변수 대체는 BigQuery를 사용하며 SQL 삽입으로부터 안전합니다. 자세한 내용은 매개변수화된 쿼리 실행을 참고하세요.

콘솔

SQL은 와일드 카드 연산자를 '모든 값'으로 해석하지 않으므로 SQL 쿼리에 변수를 적용할 때는 항상 IF 문을 사용하는 것이 좋습니다. 다음 예는 데이터 유형이 문자열인 값 전용 변수의 사용을 보여줍니다.

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

변수의 메뉴 옵션을 통해 사용자가 여러 값을 선택할 수 있는 경우 CAST 함수를 사용하여 변수의 값을 GoogleSQL 데이터 유형으로 변환해야 합니다. 다음 쿼리는 이 문법을 보여줍니다.

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

SQL은 와일드 카드 연산자를 '모든 값'으로 해석하지 않으므로 이전 예에 표시된 IF 문이 권장됩니다. 따라서 IF 문을 생략하고 와일드 카드 연산자를 선택하면 쿼리 결과는 빈 테이블이 됩니다. 두 번째 예에서 UNNEST 함수는 배열을 테이블로 변환합니다.

올바른 형식의 WHERE 절을 추가하려면 다음 단계를 따르세요.

1. 위젯을 수정합니다.
2. 툴바에서 변수 필터 삽입을 선택한 다음 WHERE 절에 적용할 변수를 선택합니다.
3. 열리는 대화상자에서 생성된 코드를 검토한 다음 복사 및 닫기를 클릭합니다.

4. 복사한 코드를 쿼리 창에 붙여넣고 필요한 사항을 수정합니다.

   예를 들어 로그 이름 목록을 생성하고 log_name이라는 단일 열이 있는 테이블에 결과를 출력하는 LogName라는 변수를 만든다고 가정해 보겠습니다. 그런 다음 차트를 만들고 변수 필터 삽입을 선택한 다음 변수 LogName를 선택합니다. 다음 코드가 생성됩니다.

   WHERE IF(@LogName = '*', TRUE, LogName = @LogName)
   

   이 예에서는 테이블 조인이 발생할 수 있도록 생성된 코드를 수정하고 LogName =를 log_name =로 바꿔야 합니다.

   WHERE IF(@LogName = '*', TRUE, log_name = @LogName)
   

5. 실행을 클릭한 다음 적용을 클릭합니다.

6. 수정된 대시보드를 저장하려면 툴바에서 저장을 클릭합니다.

API

SQL은 와일드 카드 연산자를 '모든 값'으로 해석하지 않으므로 SQL 쿼리에 변수를 적용할 때는 항상 IF 문을 사용하는 것이 좋습니다. 다음 예는 데이터 유형이 문자열인 값 전용 변수의 사용을 보여줍니다.

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

예를 들어 다음은 SQL 쿼리의 결과를 표시하는 차트의 부분 JSON 표현을 보여줍니다. 로그 이름으로 결과를 필터링할 수 있도록 LogName라는 변수를 참조하는 WHERE 절이 추가되었습니다.

"plotType": "STACKED_BAR",
"targetAxis": "Y1",
"timeSeriesQuery": {
  "opsAnalyticsQuery": {
    "queryExecutionRules": {},
    "queryHandle": "",
    "sql": "SELECT\n timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload\n
            FROM\n `my-project.global._Default._Default`\n
            WHERE \n IF (@LogName = \"*\", TRUE, log_name=@LogName)\nLIMIT 10000"
  }
}

변수 LogName는 가능한 로그 이름 목록을 확인하기 위한 쿼리도 실행합니다.

"dashboardFilters": [
  {
    "filterType": "VALUE_ONLY",
    "templateVariable": "LogName",
    "valueType": "STRING",
    "timeSeriesQuery": {
      "opsAnalyticsQuery": {
        "savedQueryId": "",
        "sql": "SELECT log_name FROM `my-project.global._Default._Default` GROUP BY log_name LIMIT 1000",
        "queryHandle": ""
      },
      "unitOverride": "",
      "outputFullDuration": false
    }
  }
],

변수의 메뉴 옵션을 통해 사용자가 여러 값을 선택할 수 있는 경우 CAST 함수를 사용하여 변수의 값을 GoogleSQL 데이터 유형으로 변환해야 합니다. 다음 쿼리는 이 문법을 보여줍니다.

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

SQL은 와일드 카드 연산자를 '모든 값'으로 해석하지 않으므로 이전 예에 표시된 IF 문이 권장됩니다. 따라서 IF 문을 생략하고 와일드 카드 연산자를 선택하면 쿼리 결과는 빈 테이블이 됩니다. 두 번째 예에서 UNNEST 함수는 배열을 테이블로 변환합니다.

MQL 쿼리가 포함된 차트

MQL 쿼리가 있는 차트에 라벨 기반 변수를 적용하려면 파이프 (|)를 추가한 다음 일반 구문에 나와 있는 안내를 따르세요.

메뉴 기반 인터페이스를 사용하여 시계열 데이터를 표시하는 차트를 만들면 선택 항목이 Monitoring 필터로 변환됩니다.

콘솔

예를 들어 다음 쿼리는 라벨 기반 변수 my_label_based_variable가 필터 표현식으로 확인되는 것을 사용합니다.

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

쿼리를 수정하여 변수의 값만 확인할 수도 있습니다. 다음 예에서는 정규 표현식을 사용하여 라벨 기반 쿼리의 값을 instance_id와 비교합니다.

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

값 전용 변수가 있는 경우 .value 절을 생략합니다. 예를 들어 값 전용 변수를 사용하여 영역별로 필터링하려면 쿼리에 다음과 같은 내용이 포함됩니다.

resource.zone=~'${my_value_only_variable}'

API

예를 들어 다음 JSON은 라벨 기반 변수 my_label_based_variable를 사용하여 필터 표현식으로 확인되는 쿼리를 보여줍니다.

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n
    | ${my_label_based_variable}",
  "unitOverride": "",
  "outputFullDuration": false
},

쿼리를 수정하여 변수의 값만 확인할 수도 있습니다. 다음 예에서는 정규 표현식을 사용하여 라벨 기반 쿼리의 값을 instance_id와 비교합니다.

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | filter resource.instance_id=~'${my_label_based_variable.value}'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n",
  "unitOverride": "",
  "outputFullDuration": false
},

값 전용 변수가 있는 경우 .value 절을 생략합니다. 예를 들어 값 전용 변수를 사용하여 영역별로 필터링하려면 쿼리에 다음과 같은 내용이 포함됩니다.

resource.zone=~'${my_value_only_variable}'

다음 표는 MQL에서 예시 변수를 확인하는 방법을 보여줍니다. 앞에서 언급했듯이 변수의 값만 사용되는 경우 정규 표현식을 비교 연산자로 사용해야 합니다.

구문	선택된 값	확인된 MQL 표현식
${my_label_based_variable}	12345	filter (resource.instance_id == '12345') 예시 변수는 리소스 라벨 instance_id을 기반으로 합니다.
${my_label_based_variable}	*	filter (true)
${my_label_based_variable.value} ${my_value_based_variable}	12345	12345
${my_label_based_variable.value} ${my_value_based_variable}	*	.*

모니터링 필터 쿼리가 포함된 차트

모니터링 필터 형식의 쿼리가 있는 차트에 라벨 기반 변수를 적용하려면 일반 문법에 나와 있는 안내를 따르세요.

콘솔

Google Cloud 콘솔을 사용하여 차트를 만들고 메뉴 기반 인터페이스를 사용하는 경우 변수의 차트에 적용 필드를 사용하거나 위젯을 수정하고 필터 메뉴에서 라벨 기반 변수를 선택하여 라벨 기반 변수를 차트에 적용할 수 있습니다. 필터 메뉴에는 모든 라벨 기반 변수와 모든 라벨 키가 표시됩니다.

이러한 유형의 차트에 값 기반 변수를 적용하려면 다음 단계를 따르세요.

1. 차트를 수정합니다.
2. 쿼리 창에서 필터 추가를 클릭하고 라벨 키를 선택합니다. 예를 들어 zone을 선택할 수 있습니다.
3. 값 메뉴에서 값 전용 변수를 선택합니다.
4. 적용을 클릭합니다.
5. 수정된 대시보드를 저장하려면 툴바에서 저장을 클릭합니다.

예를 들어 다음 JSON은 라벨 기반 변수 my_label_based_variable를 사용하여 필터 표현식으로 확인되는 쿼리를 보여줍니다.

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance" ${my_label_based_variable}"

Monitoring 필터 형식의 쿼리를 사용하는 위젯은 라벨 기반 변수의 값으로 시계열을 필터링할 수 없지만 값 전용 변수로 필터링할 수는 있습니다. 예를 들어 다음 쿼리는 값 전용 변수의 값을 기반으로 zone로 필터링하는 쿼리의 Filters 필드 값을 보여줍니다.

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance"
resource.label."zone"=monitoring.regex.full_match(${my_value_only_variable})

API

예를 들어 다음 JSON은 라벨 기반 변수 my_label_based_variable를 사용하여 필터 표현식으로 확인되는 쿼리를 보여줍니다.

"timeSeriesQuery": {
  "timeSeriesFilter": {
    "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
               resource.type=\"gce_instance\"
               ${my_label_based_variable} ",
    "aggregation": {
      "alignmentPeriod": "60s",
      "perSeriesAligner": "ALIGN_MEAN",
      "groupByFields": []
    }
  },
  "unitOverride": "",
  "outputFullDuration": false
},

Monitoring 필터 형식의 쿼리를 사용하는 위젯은 라벨 기반 변수의 값으로 시계열을 필터링할 수 없지만 값 전용 변수로 필터링할 수는 있습니다. 예를 들어 다음 쿼리는 값 전용 변수의 값을 기반으로 zone로 필터링하는 쿼리의 "filter" 필드를 보여줍니다.

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
          resource.type=\"gce_instance\"
          resource.labels.\"zone\"=monitoring.regex.full_match(${my_value_only_variable})"

다음 표는 모니터링 필터에서 예시 변수를 확인하는 방법을 보여줍니다. 앞에서 언급했듯이 변수의 값만 사용되는 경우 정규 표현식을 비교 연산자로 사용해야 합니다.

구문	선택된 값	해결된 필터 표현식
${my_label_based_variable}	12345	resource.instance_id == "12345" 예시 변수는 리소스 라벨 instance_id을 기반으로 합니다.
${my_label_based_variable}	*	중략
${my_label_based_variable.value}	12345	지원되지 않음
${my_label_based_variable.value}	*	지원되지 않음
${my_value_based_variable}	12345	"12345"
${my_value_based_variable}	*	".*"

대시보드 만들기

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

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

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

API

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

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

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

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

Terraform

Terraform 구성을 적용하거나 삭제하는 방법은 기본 Terraform 명령어를 참조하세요. 자세한 내용은 Terraform 제공업체 참고 문서를 확인하세요.

참고: Terraform을 사용하여 대시보드를 만들면 Google Cloud 콘솔에서 대시보드를 볼 수 있습니다. 하지만 Google Cloud 콘솔에서는 대시보드를 수정하지 마세요. 수정하면 대시보드 크기가 조정됩니다. 자세한 내용은 문제 해결: Terraform으로 만든 대시보드의 크기가 조정됨을 참고하세요.

Terraform을 사용하여 대시보드를 만들려면 Terraform 리소스 google_monitoring_dashboard를 사용합니다.

명령어에서 다음 필드를 설정합니다.

• dashboard_json: Dashboards 형식을 사용하는 대시보드의 JSON 표현입니다.

  이 형식의 예를 보려면 API Explorer를 사용하여 대시보드를 나열하거나 Google Cloud 콘솔에서 대시보드를 열고 JSON 표현을 확인하면 됩니다.

• parent: 프로젝트의 정규화된 이름입니다. 예를 들어 이 필드를 "projects/PROJECT_ID"로 설정할 수 있습니다. 여기서 PROJECT_ID는 Google Cloud 프로젝트 ID입니다.

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

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

대시보드 삭제

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

API

커스텀 대시보드를 삭제하려면 삭제할 대시보드의 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 참조 문서를 확인하세요.

Terraform

Terraform을 사용하여 리소스를 삭제할 수 있습니다. 리소스 삭제에 관한 자세한 내용은 Terraform 명령어 destroy를 참고하세요.

대시보드 나열

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

API

프로젝트의 모든 커스텀 대시보드를 나열하려면 프로젝트 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 참조를 확인하세요.

Terraform

Terraform을 사용하여 대시보드 목록이 응답인 프로젝트에 쿼리를 전송할 수는 없습니다. 하지만 Google Cloud 콘솔을 사용하여 이러한 대시보드를 볼 수 있습니다.

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

list 응답을 페이지로 나누기

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

API

결과 목록의 첫 페이지에 요청과 함께 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

Terraform

Terraform을 사용하여 대시보드의 페이지로 나뉜 목록이 응답으로 반환되는 프로젝트 쿼리를 전송할 수는 없습니다. 하지만 Google Cloud 콘솔을 사용하여 이러한 대시보드를 볼 수 있습니다.

대시보드 가져오기

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

API

특정 커스텀 대시보드를 가져오려면 대시보드 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 참조를 확인하세요.

Terraform

Terraform을 사용하여 응답이 개별 대시보드인 프로젝트에 쿼리를 보낼 수는 없습니다. 하지만 Google Cloud 콘솔을 사용하여 이러한 대시보드를 볼 수 있습니다.

대시보드 업데이트

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

API

커스텀 대시보드를 업데이트하려면 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}

이전 예에서는 my-updated-dashboard.json 파일을 사용하여 기존 커스텀 대시보드를 업데이트합니다. 새 etag 값이 포함된 응답은 업데이트된 대시보드 목록의 사본입니다.

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 값이 포함된 응답은 업데이트된 대시보드 목록의 사본입니다.

Terraform

Terraform 구성을 적용하거나 삭제하는 방법은 기본 Terraform 명령어를 참조하세요. 자세한 내용은 Terraform 제공업체 참고 문서를 확인하세요.

Terraform을 사용하여 대시보드를 업데이트하려면 Terraform 리소스 google_monitoring_dashboard를 사용합니다.

명령어에서 다음 필드를 설정합니다.

• dashboard_json: Dashboards 형식을 사용하는 대시보드의 JSON 표현입니다.

• parent: 프로젝트의 정규화된 이름입니다. 예를 들어 이 필드를 "projects/PROJECT_ID"로 설정할 수 있습니다. 여기서 PROJECT_ID는 Google Cloud 프로젝트 ID입니다.

다음 단계

• 대시보드 및 레이아웃 예시
• Google Cloud 콘솔로 커스텀 대시보드 만들기 및 관리