사용자 정의 문서로 알림에 주석 추가

이 페이지에서는 알림이 이슈 대응자에게 이슈 해결을 위한 리소스와 추가 정보를 제공하도록 알림 정책 문서를 구성하는 방법을 설명합니다.

문서 구조

알림 정책 문서는 제목, 콘텐츠, 링크로 구성됩니다. Google Cloud 콘솔, Cloud Monitoring API, Google Cloud CLI에서 문서를 구성할 수 있습니다.

제목

문서 제목은 알림 정책과 관련된 이슈의 알림 제목에 표시됩니다. 알림 수신자는 제목별로 알림을 관리하고 정렬할 수 있습니다.

제목은 255자(영문 기준)로 제한됩니다. 문서에서 제목을 정의하지 않으면 Cloud Monitoring이 제목을 결정합니다. 제목은 일반 텍스트와 변수를 지원합니다.

Cloud Monitoring API

알림 정책 documentation의 subject 필드를 사용하여 알림 제목을 구성합니다.

Google Cloud 콘솔

알림 정책 만들기 페이지의 알림 및 이름 섹션에 있는 알림 제목 필드를 사용하여 알림 제목을 구성합니다.

콘텐츠

문서 콘텐츠는 다음 알림 유형에 표시됩니다.

이메일(정책 문서 헤더 아래)
PagerDuty
Pub/Sub
Slack
웹훅

이슈 대응자가 알림 정책과 관련된 알림에서 해결 단계와 이슈 정보를 볼 수 있도록 콘텐츠를 구성하는 것이 좋습니다. 예를 들어 이슈 요약과 관련 리소스에 대한 정보가 포함되도록 문서를 구성할 수 있습니다.

문서 콘텐츠는 일반 텍스트, 마크다운, 변수, 채널별 컨트롤을 지원합니다.

Cloud Monitoring API

알림 정책 documentation의 content 필드를 사용하여 문서 콘텐츠를 구성합니다.

Google Cloud 콘솔

알림 정책 만들기 페이지의 알림 및 이름 섹션에 있는 문서 필드를 사용하여 문서 콘텐츠를 구성합니다.

링크

이슈 대응자가 알림에서 플레이북, 저장소, Google Cloud 대시보드와 같은 리소스에 액세스할 수 있도록 문서에 링크를 추가할 수 있습니다.

Cloud Monitoring API

Cloud Monitoring API에 구성된 문서 링크는 다음 알림 유형에 표시됩니다.

이메일(빠른 링크 헤더 아래)
PagerDuty
Pub/Sub
웹훅

링크를 구성하려면 알림 정책의 documentation에 Link를 추가합니다. 각 링크는 display_name 및 url로 표시됩니다. 문서에 링크를 최대 3개까지 포함할 수 있습니다.

다음 구성은 URL 하나가 있는 links를 사용하여 이슈 플레이북에 대한 링크를 만듭니다. URL에는 알림 수신자가 이슈가 발생한 모니터링 리소스를 기반으로 올바른 플레이북에 액세스할 수 있도록 변수가 포함되어 있습니다.

"links" [
  {
    "displayName": "Playbook",
    "url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
  }
]

Google Cloud 콘솔

Google Cloud 콘솔에서 구성된 문서 링크는 다음 알림 유형에서 나머지 문서 콘텐츠와 함께 표시됩니다.

이메일(정책 문서 헤더 아래)
PagerDuty
Pub/Sub
Slack
웹훅

알림 정책의 문서 필드에 문서 콘텐츠에 대한 링크를 포함하여 추가할 수 있습니다. 예를 들어 다음 문서에는 고객 플레이북의 URL이 나와 있습니다.

### Troubleshooting and Debug References

Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}

문서 콘텐츠의 마크다운

마크다운을 사용하여 문서 콘텐츠 형식을 지정할 수 있습니다. 문서 콘텐츠는 다음과 같은 마크다운 태그 하위 집합을 지원합니다.

맨 앞에 해시(#) 문자로 표시된 헤더
맨 앞에 더하기(+), 빼기(-), 또는 별표(*)가 표시된 순서가 지정되지 않은 목록
맨 앞에 숫자와 마침표(.)가 차례로 있는 순서가 지정된 목록
문구 앞뒤에 1개의 밑줄(_) 또는 별표(*)가 표시된 기울임꼴 텍스트
문구 앞뒤에 2개의 밑줄(_) 또는 별표(*)가 표시된 볼드체 텍스트
[link text](url) 구문으로 표시된 링크 하지만 Link 객체를 사용하여 콘텐츠에 대한 링크를 구성하는 것이 좋습니다.

이 태그 지정에 대한 자세한 내용은 마크다운 참조(예를 들어 마크다운 가이드)를 참조하세요.

문서의 변수

문서의 텍스트를 맞춤설정하려면 ${varname} 형식의 변수를 사용하면 됩니다. 문서를 알림과 함께 전송하면 ${varname} 문자열이 다음 표에 설명된 대로 해당 Google Cloud 리소스에서 가져온 값으로 대체됩니다.

변수	값
`condition.name`	조건의 REST 리소스 이름(예: )`projects/foo/alertPolicies/1234/conditions/5678`
`condition.display_name`	조건의 표시 이름(예: `CPU usage increasing rapidly`)
`log.extracted_label.KEY`	로그 항목에서 추출한 `KEY` 라벨의 값. (로그 기반 알림 정책만 해당) 자세한 내용은 Monitoring API를 사용하여 로그 기반 알림 정책 만들기를 참조하세요.
`metadata.system_label.KEY`	시스템 제공 리소스 메타데이터 라벨 `KEY`의 값입니다.¹
`metadata.user_label.KEY`	사용자 정의 리소스 메타데이터 라벨 `KEY`의 값입니다.^1,3
`metric.type`	측정항목 유형(예: )`compute.googleapis.com/instance/cpu/utilization`
`metric.display_name`	측정항목 유형의 표시 이름(예: `CPU utilization`)
`metric.label.KEY`	측정항목 라벨 `KEY`의 값입니다.¹ 측정항목 유형과 연결된 라벨을 찾으려면 측정항목 목록을 참조하세요. 변수 `${metric.label.KEY}`의 값이 숫자, 문자, 슬래시(`/`) 또는 등호(`=`)로 시작되지 않으면 Monitoring은 알림에서 라벨을 생략합니다. Prometheus 알림 규칙을 마이그레이션하면 Prometheus 알림 필드 템플릿 `{{$value}}`와 `{{humanize $value}}`가 알림 정책 문서 구성에서 `${metric.label.VALUE}`로 표시됩니다. 이 경우 `VALUE`는 PromQL 쿼리 값을 포함합니다. Google Cloud에서 PromQL 쿼리를 만들 때 `${metric.label.VALUE}`를 사용할 수도 있습니다.
`metric_or_resource.labels`	이 변수는 모든 측정항목 라벨 값과 리소스 라벨 값을 정렬된 `key-value` 쌍 목록으로 렌더링합니다. 측정항목 라벨과 리소스 라벨의 이름이 같으면 측정항목 라벨만 렌더링됩니다. Prometheus 알림 규칙을 마이그레이션하면 Prometheus 알림 필드 템플릿 `{{$labels}}`와 `{{humanize $labels}}`가 알림 정책 문서 구성에서 `${metric_or_resource.labels}`로 표시됩니다.
`metric_or_resource.label.KEY`	`KEY`가 유효한 라벨이면 이 변수는 알림에서 `${metric.label.KEY}` 값으로 렌더링됩니다. `KEY`가 유효한 리소스면 이 변수는 알림에서 `${resource.label.KEY}` 값으로 렌더링됩니다. `KEY`가 유효한 라벨이나 유효한 리소스가 아니면 이 변수는 알림에서 빈 문자열로 렌더링됩니다. Prometheus 알림 규칙을 마이그레이션하면 Prometheus 알림 필드 템플릿 `{{$labels.KEY}}`와 `{{humanize $labels.KEY}}`가 알림 정책 문서 구성에서 `${metric_or_resource.labels.KEY}`로 표시됩니다.
`policy.name`	정책의 REST 리소스 이름(예: `projects/foo/alertPolicies/1234`)
`policy.display_name`	정책의 표시 이름(예: `High CPU rate of change`)
`policy.user_label.KEY`	사용자 라벨 `KEY`의 값.¹ 키는 소문자로 시작해야 합니다. 키와 값에는 소문자, 숫자, 밑줄, 대시만 사용할 수 있습니다.
`project`	측정항목 범위의 범위 프로젝트 ID입니다(예: `a-gcp-project`).
`resource.type`	모니터링 리소스 유형입니다(예: `gce_instance`).
`resource.project`	알림 정책 모니터링 리소스의 프로젝트 ID
`resource.label.KEY`	리소스 라벨 `KEY`의 값입니다.^1,2,3 모니터링 리소스 유형과 연결된 라벨을 찾으려면 리소스 목록을 참조하세요.

¹ 예를 들어 ${resource.label.zone}는 zone 라벨 값으로 바뀝니다. 이러한 변수의 값은 그룹화됩니다. 자세한 내용은 null 값을 참조하세요.
² 알림 정책에서 모니터링 리소스의 project_id 라벨 값을 검색하려면 ${resource.project}를 사용합니다.
³ resource.label.KEY.를 사용하여 사용자 정의 리소스 메타데이터 라벨에 액세스할 수 없습니다. 대신 metadata.user_label.KEY를 사용하세요.

사용 참고사항

표에 나온 변수만 지원됩니다. ${varname1 + varname2}와 같이 더 복잡한 표현식으로 변수를 결합할 수 없습니다.
문서에 리터럴 문자열 ${을 포함하려면 두 번째 $ 기호로 $ 기호를 이스케이프 처리합니다. 그러면 문서에서 $${가 ${로 렌더링됩니다.
이러한 변수는 알림 채널을 통해 전송된 알림에서만 값으로 대체됩니다. Google Cloud Console에서 문서가 표시되면 값이 아닌 변수가 표시됩니다. 콘솔의 예시에는 이슈에 대한 설명과 알림 정책을 만들 때의 문서 미리보기가 포함됩니다.
조건의 집계 설정에서 라벨이 삭제되지 않도록 합니다. 라벨이 삭제되면 알림의 라벨 값은 null입니다. 자세한 내용은 측정항목 라벨에 대한 변수가 null임을 참조하세요.

`null` 값

metric.*, resource.*, metadata.* 변수의 값은 시계열에서 파생됩니다. 시계열 쿼리에서 반환된 값이 없는 경우 값은 null일 수 있습니다.

알림 정책이 교차 계열 집계(감소)를 사용하는 경우 resource.label.KEY 및 metric.label.KEY 변수는 null 값을 가질 수 있습니다(예: 필터와 일치하는 각 시계열에서 SUM을 계산하는 경우). 교차 계열 집계를 사용하면 그룹화에 사용되지 않은 라벨이 모두 삭제되고 변수가 값으로 대체될 때 null로 렌더링됩니다. 모든 라벨은 교차 계열 집계가 없어도 유지됩니다. 자세한 내용은 측정항목 라벨에 대한 변수가 null임을 참조하세요.
metadata.* 변수의 값은 라벨이 교차 계열 집계의 조건 필터 또는 그룹화에 명시적으로 포함된 경우에만 사용할 수 있습니다. 즉, 템플릿의 값을 갖도록 필터 또는 그룹화에서 메타데이터 라벨을 참조해야 합니다.

변수 확인

문서 템플릿의 변수는 다음 알림 채널을 사용하여 전송된 알림에서만 확인됩니다.

이메일
Google Chat
Slack
Pub/Sub, JSON 스키마 버전 1.2
Webhooks, JSON 스키마 버전 1.2
PagerDuty, JSON 스키마 버전 1.2

채널 컨트롤

알림 채널에서 사용하는 특수 문자를 문서 필드의 텍스트에 포함시켜 형식 지정 및 알림을 컨트롤할 수도 있습니다.

예를 들어 Slack에서는 멘션에 @를 사용합니다. @를 사용하여 알림을 특정 사용자 ID에 연결할 수 있습니다. 멘션에는 이름이 포함될 수 없습니다. 이와 같은 문자열을 문서 필드에 포함한다고 가정해 보겠습니다.

<@backendoncall> Incident created based on policy ${policy.display_name}

관련 Slack 채널에서 알림의 일부로 문서 필드를 수신하면 이전 문자열로 인해 Slack에서 추가 메시지를 사용자 ID backendoncall에 전송합니다. Slack이 사용자에게 보낸 메시지에는 '높은 CPU 변경률 정책을 기반으로 생성된 이슈'와 같은 알림의 관련 정보가 포함될 수 있습니다.

제공되는 추가 옵션은 채널마다 다릅니다. 사용 가능한 옵션에 대한 자세한 내용은 채널 공급업체가 제공하는 문서를 참조하세요.

예

다음 예시에서는 CPU 사용률 알림 정책에 대한 템플릿 문서의 Google Cloud 콘솔 및 Cloud Monitoring API 버전을 보여줍니다. 이 예시에서는 알림 채널 유형으로 이메일을 사용합니다. 문서 템플릿에는 이슈를 요약하고 알림 정책과 조건 REST 리소스를 참조하는 몇 가지 변수가 포함되어 있습니다.

Cloud Monitoring API

  "documentation": {
    "content": "### CPU utilization exceeded\n\n### Summary\n\nThe ${metric.display_name} of the ${resource.type} ${resource.label.instance_id} in the project ${resource.project} has exceeded 5% for over 60 seconds.\n\n#### Additional resource information\n\nCondition resource name: ${condition.name}  \nAlerting policy resource name: ${policy.name}",
    "mimeType": "text/markdown",
    "subject": "Alert: ${metric.display_name} exceeded",
    "links": [
      {
        "displayName": "Playbook",
        "url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
      },
      {
        "displayName": "Repository with debug scripts",
        "url": "https://altostrat.com"
      },
      {
        "displayName": "Google Cloud dashboard",
        "url": "https://example.com"
      }
    ]
  }

다음 이미지에서는 이 템플릿이 이메일 알림에 표시되는 방식을 보여줍니다.

알림에서 문서가 렌더링되는 방법의 예시 링크는 '빠른 링크' 섹션에 표시됩니다.

Google Cloud 콘솔

### CPU utilization exceeded

#### Summary

The ${metric.display_name} of the ${resource.type}
${resource.label.instance_id} in the project ${resource.project} has
exceeded 5% for over 60 seconds.

#### Additional resource information

Condition resource name: ${condition.name}  
Alerting policy resource name: ${policy.name}  

#### Troubleshooting and Debug References

Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}  
Repository with debug scripts: https://altostrat.com  
${resource.type} dashboard: https://example.com

다음 이미지에서는 이 템플릿이 이메일 알림에 표시되는 방식을 보여줍니다.

알림에서 문서가 렌더링되는 방법의 예시 링크는 '문제 해결 및 디버그 참조' 헤더 아래에 표시됩니다.

사용자 정의 문서로 알림에 주석 추가

문서 구조

제목

Cloud Monitoring API

Google Cloud 콘솔

콘텐츠

Cloud Monitoring API

Google Cloud 콘솔

링크

Cloud Monitoring API

Google Cloud 콘솔

문서 콘텐츠의 마크다운

문서의 변수

사용 참고사항

null 값

변수 확인

채널 컨트롤

예

Cloud Monitoring API

Google Cloud 콘솔

`null` 값