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

이 페이지에서는 알림 정책 문서를 구성하여 알림의 본문과 제목을 맞춤설정하는 방법을 설명합니다. 문서 필드는 일반 텍스트, 마크다운, 변수 및 채널별 컨트롤을 지원합니다.

알림에 정보 추가

알림 정책을 만들 때 해당 콘텐츠를 지정하여 알림에서 이슈에 대한 해결 단계 및 정보를 이슈 대응자에게 제공할 수 있습니다. 예를 들어 모든 알림에 내부 플레이북 링크를 포함하도록 알림 정책을 구성할 수 있습니다.

샘플 구현은 이 페이지의 예시 섹션을 참조하세요.

알림 제목 구성

알림의 제목을 지정하여 알림을 관리하고 정렬할 수 있습니다. 제목은 255자(영문 기준)로 제한됩니다. 문서에서 제목을 정의하지 않으면 Cloud Monitoring이 제목을 결정합니다.

Cloud Monitoring API, Google Cloud CLI 또는 Google Cloud 콘솔을 사용할 때 제목을 구성할 수 있습니다.

샘플 구현은 이 페이지의 예시 섹션을 참조하세요.

마크다운 사용

문서 필드는 다음과 같은 마크다운 태그 하위 집합을 지원합니다.

  • 맨 앞에 해시(#) 문자로 표시된 헤더
  • 맨 앞에 더하기(+), 빼기(-), 또는 별표(*)가 표시된 순서가 지정되지 않은 목록
  • 맨 앞에 숫자와 마침표(.)가 차례로 있는 순서가 지정된 목록
  • 문구 앞뒤에 1개의 밑줄(_) 또는 별표(*)가 표시된 기울임꼴 텍스트
  • 문구 앞뒤에 2개의 밑줄(_) 또는 별표(*)가 표시된 볼드체 텍스트
  • [link text](url) 구문으로 표시된 링크

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

변수 사용

${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의 값입니다.1
metadata.user_label.KEY 사용자 정의 리소스 메타데이터 라벨 KEY의 값입니다.1,3
metric.type 측정항목 유형(예:
)compute.googleapis.com/instance/cpu/utilization
metric.display_name 측정항목 유형의 표시 이름(예: CPU utilization)
metric.label.KEY

측정항목 라벨 KEY의 값입니다.1
측정항목 유형과 연결된 라벨을 찾으려면 측정항목 목록을 참조하세요.

변수 ${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의 값.1

키는 소문자로 시작해야 합니다. 키와 값에는 소문자, 숫자, 밑줄, 대시만 사용할 수 있습니다.

project 측정항목 범위의 범위 프로젝트 ID입니다(예: a-gcp-project).
resource.type 모니터링 리소스 유형입니다(예: gce_instance).
resource.project 알림 정책 모니터링 리소스의 프로젝트 ID
resource.label.KEY 리소스 라벨 KEY의 값입니다.1,2,3
모니터링 리소스 유형과 연결된 라벨을 찾으려면 리소스 목록을 참조하세요.

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

사용 참고사항

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

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

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 90% for over 15 minutes.

### Additional resource information

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

### Troubleshooting and Debug References

Repository with debug scripts: example.com
Internal troubleshooting guide: example.com
${resource.type} dashboard: example.com

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 90% for over 15 minutes.\n\n### Additional resource information\n\nCondition resource name: ${condition.name}  \nAlerting policy resource name: ${policy.name}  \n\n### Troubleshooting and Debug References\n    \nRepository with debug scripts: example.com  \nInternal troubleshooting guide: example.com  \n${resource.type} dashboard: example.com",
"mimeType": "text/markdown",
"subject": "Alert: ${metric.display_name} exceeded"
}

알림 형식

알림에서 문서가 렌더링되는 방법의 예시

null

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

  • 알림 정책이 교차 계열 집계(감소)를 사용하는 경우 resource.label.KEYmetric.label.KEY 변수는 null 값을 가질 수 있습니다(예: 필터와 일치하는 각 시계열에서 SUM을 계산하는 경우). 교차 계열 집계를 사용하면 그룹화에 사용되지 않은 라벨이 모두 삭제되고 변수가 값으로 대체될 때 null로 렌더링됩니다. 모든 라벨은 교차 계열 집계가 없어도 유지됩니다. 자세한 내용은 측정항목 라벨의 변수가 null임을 참조하세요.

  • metadata.* 변수의 값은 라벨이 교차 계열 집계의 조건 필터 또는 그룹화에 명시적으로 포함된 경우에만 사용할 수 있습니다. 즉, 템플릿의 값을 갖도록 필터 또는 그룹화에서 메타데이터 라벨을 참조해야 합니다.

변수 확인

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

  • 이메일
  • Slack
  • Pub/Sub, JSON 스키마 버전 1.2
  • 웹훅, JSON 스키마 버전 1.2
  • PagerDuty, JSON 스키마 버전 1.2

변수는 확인되지 않지만 다른 컨텍스트에서 다음을 포함하여 ${varname}과 같은 문자열로 표시됩니다.

  • Google Cloud 콘솔의 이슈 세부정보 페이지
  • 다른 알림 채널을 사용하여 보낸 알림

채널 컨트롤 사용

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

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

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

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

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