사용자 정의 이벤트 알림 템플릿¶

템플릿 문법을 사용하여 이벤트 알림 내용을 사용자 정의할 수 있습니다:

동적 렌더링: {{ 필드명 }}을 사용하여 알림 필드를 직접 삽입합니다 (예: {{ host }}, {{ df_status }}).
데이터 처리: {{ 변수 | 함수() }}를 통해 데이터를 포맷합니다 (예: 타임스탬프를 날짜로 변환, 숫자를 백분율로 변환).
조건 분기: {% if ... %}를 사용하여 상태에 따라 다른 알림을 전송합니다.
실시간 조회: DQL ("쿼리문")을 삽입하여 관련 데이터를 가져옵니다 (예: 호스트 IP, 애플리케이션 정보).

기본 템플릿 변수¶

템플릿 변수의 기본 문법은 {{ 필드명 }}이며, 이벤트 관련 동적 정보를 렌더링하는 데 사용됩니다. 다음은 일반적인 템플릿 변수와 그 용도입니다:

템플릿 변수	타입	설명
`date`, `timestamp`	정수	이벤트 발생 시간. 단위는 초
`df_date_range`	정수	시간 범위. 단위는 초
`df_check_range_start`	정수	검사 범위 시작 시간. Unix 타임스탬프, 단위는 초
`df_check_range_end`	정수	검사 범위 종료 시간. Unix 타임스탬프, 단위는 초
`df_status`	문자열(열거형)	이벤트 상태, 가능한 값: 긴급 `critical` 중요 `error` 경고 `warning` 정상 `ok` 데이터 단절 `nodata`
`df_event_id`	문자열	이벤트 고유 ID
`df_event_link`	문자열	이벤트 상세 페이지 링크 주소
`df_dimension_tags`	문자열	이벤트 차원. 검사 대상을 식별하는 데 사용 예: `{"host":"web-001"}`
`df_monitor_id`	문자열	알림 정책 ID
`df_monitor_name`	문자열	알림 정책 이름
`df_monitor_checker_id`	문자열	모니터 ID
`df_monitor_checker_name`	문자열	모니터 이름
`df_monitor_checker_value`	문자열	검사 값, 즉 모니터가 검사한 값 ❗️검사 값은 호환성을 위해 강제로 문자열 타입으로 변환됩니다
`df_monitor_checker_event_ref`	문자열	모니터 이벤트 연결. 모니터 ID, 이벤트 `df_dimension_tags`를 기준으로 계산됩니다
`df_fault_id`	문자열	현재 장애 ID, 첫 번째 장애 이벤트의 `df_event_id` 값을 사용합니다
`df_fault_status`	문자열(열거형)	현재 장애 상태, `df_status`의 중복 필드입니다. 가능한 값: 정상 `ok` 장애 `fault`
`df_fault_start_time`	정수	현재 장애 발생 시간. Unix 타임스탬프, 단위는 초
`df_fault_duration`	정수	현재 장애 지속 시간. 단위는 초
`df_user_id`	문자열	수동 복구 시, 작업자 사용자 ID
`df_user_name`	문자열	수동 복구 시, 작업자 사용자 이름
`df_user_email`	문자열	수동 복구 시, 작업자 사용자 이메일
`df_crontab_exec_mode`	문자열(열거형)	모니터 실행 모드, 가능한 값: 자동 트리거 `crontab` 수동 실행 `manual`
`df_site_name`	문자열	현재 Guance 노드명
`df_workspace_name`	문자열	소속 워크스페이스명
`df_workspace_uuid`	문자열	소속 워크스페이스 ID
`df_label`	리스트	모니터 태그 목록
`df_check_condition`	딕셔너리	충족된 검사 조건
`df_check_detail`	딕셔너리	돌연변이 검사에 적용되며, 원본 값과의 비교를 나타냅니다. 세 가지 필드를 포함합니다: 표시 검사값 (`change_value`) 비교값 (`comparison_value`) 변경값 (`detection_value`)
`df_check_condition.operator`	문자열	충족된 검사 조건의 연산자, 예: `>`, `>=` 등
`df_check_condition.operands`	리스트	충족된 검사 조건의 피연산자 목록. 일반적으로 1개의 피연산자를 가지지만, `between` 등의 연산자는 2개의 피연산자를 가집니다
`df_check_condition.operands[#]`	정수, 실수	충족된 검사 조건의 피연산자
`Result`	정수, 실수	검사된 값, `df_monitor_checker_value`와 동일하게 검사 시 생성된 값이지만, 필드 타입은 검사 시의 원래 타입이며 강제로 문자열로 변환되지 않습니다
`df_dimension_tags` 의 각 필드	문자열	`df_dimension_tags` 의 각 필드가 추출됩니다
`df_event`	딕셔너리	전체 이벤트 데이터
`df_studio_env_name`		현재 환경 이름
`df_studio_console_base_url`		현재 환경 콘솔 주소
`df_studio_monitor_base_link`		현재 환경 모니터 주소

템플릿 변수 예시¶

모니터 by에 region과 host가 구성되어 있고, 이벤트 내용 템플릿이 다음과 같다고 가정합니다:

이벤트 이름:

모니터 {{ df_monitor_checker_name }}이(가) {{ df_dimension_tags }}에서 장애를 발견했습니다

이벤트 내용:

- 지역: {{ region }}
- 호스트: {{ host }}
- 수준: {{ df_status }}
- 검사값: {{ Result }}
- 모니터: {{ df_monitor_checker_name }} (알림 정책: {{ df_monitor_name }})

그러면 error 이벤트가 발생한 후, 렌더링된 이벤트 출력은 다음과 같습니다:

출력 이벤트 이름:

모니터 모니터001이(가) {"region":"hangzhou","host":"web-001"}에서 장애를 발견했습니다

출력 이벤트 내용:

- 지역: hangzhou
- 호스트: web-001
- 수준: error
- 검사값: 90.12345
- 모니터: 모니터001 (알림 정책: 팀001)

특수 시나리오 변수¶

RUM 메트릭 검사¶

RUM 메트릭 검사에서는 위의 일반 템플릿 변수 외에도 다음 템플릿 변수를 추가로 지원합니다:

템플릿 변수	타입	설명
`app_id`	문자열	애플리케이션 ID
`app_name`	문자열	애플리케이션 이름
`app_type`	문자열	애플리케이션 타입

특수 문자 필드 처리¶

검사 구성에서 차원 필드에 특수 문자(예: -, @)가 포함된 경우(예: host-name, @level), 일반 변수명으로 직접 사용할 수 없어 템플릿 렌더링이 실패할 수 있습니다.

해결 방법은 다음 형식을 사용하여 참조하는 것입니다:

{{ host-name }} 대신 {{ df_event['host-name'] }} 사용
{{ @level }} 대신 {{ df_event['@level'] }} 사용

템플릿 함수¶

이벤트의 필드 값을 직접 표시하는 것 외에도 템플릿 함수를 사용하여 필드 값을 추가로 처리하고 출력을 최적화할 수 있습니다.

기본 문법은 다음과 같습니다:

{{ <템플릿 변수> | <템플릿 함수> }}

구체적인 예는 다음과 같습니다:

이벤트 발생 시간: {{ date | to_datetime }}

템플릿 함수에 매개변수를 전달해야 하는 경우 문법은 다음과 같습니다:

이벤트 발생 시간: {{ date | to_datetime('America/Chicago') }}

Warning

템플릿 함수를 사용하기 전에 템플릿 변수에 대해 연산을 수행해야 하는 경우 괄호를 추가하는 것을 잊지 마십시오. 예:

CPU 사용률: {{ (Result * 100) | to_round(2) }}

사용 가능한 템플릿 함수 목록은 다음과 같습니다:

템플릿 함수	매개변수	설명
`to_datetime`	시간대	타임스탬프를 날짜로 변환 (기본 시간대는 `Asia/Shanghai`) 예시: `{{ date \| to_datetime }}` 출력: `2022-01-01 01:23:45`
`to_date_range_human`		`df_fault_duration`을 읽기 쉬운 형식으로 변환 예시: `{{ df_fault_duration \| to_date_range_human }}` 출력: `X일 Y시간 Z분 W초`
`to_status_human`		`df_status`를 읽기 쉬운 형식으로 변환 예시: `{{ df_status \| to_status_human }}` 출력: `긴급`
`to_fixed`	소수 자릿수	숫자를 고정 소수 자릿수로 출력 (기본값은 소수점 0자리) 예시: `{{ Result \| to_fixed(3) }}` 출력: `1.230`
`to_round`	소수 자릿수	숫자를 반올림 (기본값은 소수점 0자리) 예시: `{{ Result \| to_round(2) }}` 출력: `1.24`
`to_percent`	소수 자릿수	소수를 백분율로 출력 (기본값은 소수점 0자리) 예시: `{{ Result \| to_percent(1) }}` 출력: `12.3%`
`to_pretty_tags`		태그를 예쁘게 출력 예시: `{{ df_dimension_tags \| to_pretty_tags }}` 출력: `region:hanghzou, host:web-001`
`limit_lines`		줄 수 제한
`limit_chars / limit_text`		문자 수 제한
`type_name`		데이터 타입 이름 출력 예시: `{{ data \| type_name }}` 출력: `dict`
`to_int`		정수로 변환 예시: `{{ data \| to_int }}<br>출력:`1`
`to_float`		실수로 변환 예시: `{{ data \| to_float }}` 출력: `1.234`
`to_str`		문자열로 변환 예시: `{{ data \| to_str }}` 출력: `1.234`
`to_json_dumps`		JSON 직렬화 문자열로 변환 예시: `{{ data \| to_json_dumps }}` 출력: `{"key1":"value1","key2":"value2"}`
`length`		데이터 길이 가져오기 예시: `{{ data \| length }}` 출력: `10`

템플릿 함수 예시¶

더 자세한 내용은 각 템플릿 함수 예시 보기를 참조하십시오.

구성된 모니터 by에 region과 host가 구성되어 있고, 알림 구성 템플릿이 다음과 같다고 가정합니다:

이벤트 이름:

모니터 {{ df_monitor_checker_name }}이(가) {{ df_dimension_tags | to_pretty_tags }}에서 장애를 발견했습니다

이벤트 내용:

- 대상: {{ df_dimension_tags | to_pretty_tags }}
- 시간: {{ date | to_datetime }}
- 수준: {{ df_status | to_status_human }}
- 검사값: {{ (Result * 100) | to_round(2) }}

그러면 error 이벤트가 발생한 후, 렌더링된 이벤트 출력은 다음과 같습니다:

출력 이벤트 이름:

모니터 내 모니터가 region:hangzhou, host:web-001에서 장애를 발견했습니다

출력 이벤트 내용:

- 검사 대상: region:hangzhou, host:web-001
- 검사 시간: 2022-01-01 01:23:45
- 장애 수준: 중요
- 검사값: 9012.35

템플릿 분기¶

템플릿은 분기 문법을 사용하여 조건에 따라 다른 내용을 렌더링하는 것도 지원합니다.

템플릿 분기 예시¶

다음 문법을 사용하여 분기 기능을 구현할 수 있습니다:

{% if df_status == 'critical' %}
긴급 문제, 즉시 처리하십시오!
{% elif df_status == 'error' %}
중요 문제, 처리하십시오
{% elif df_status == 'warning' %}
문제가 있을 수 있습니다, 시간 있을 때 처리하십시오
{% elif df_status == 'nodata' %}
데이터가 중단되었습니다, 즉시 처리하십시오!
{% else %}
문제 없습니다!
{% endif %}

더 전형적인 예는 다음과 같습니다:

{% if  df_status != 'ok' %}
> 수준: {{ df_status }}
> 호스트: {{ host }}
> 내용: Elasticsearch JVM 힙 메모리 사용량이 {{ Result }}%입니다
> 제안: 현재 JVM 가비지 수집이 JVM 가비지 생성을 따라가지 못하고 있습니다. 비즈니스 상황을 확인하십시오

{% else %}
> 수준: {{df_status}}
> 호스트: {{host}}
> 내용: Elasticsearch JVM 힙 메모리 알림이 복구되었습니다

{% endif %}

내장 DQL 쿼리 함수¶

경우에 따라 템플릿 변수만으로는 렌더링 요구 사항을 충족할 수 없습니다. 이때 내장 DQL 쿼리 함수를 사용하여 추가 데이터를 조회할 수 있습니다.

내장 DQL 쿼리 함수는 현재 워크스페이스의 이번 검사 시간 범위 내에서 모든 DQL 문을 실행할 수 있습니다. 일반적으로 쿼리로 얻은 첫 번째 데이터는 템플릿에서 템플릿 변수로 사용할 수 있습니다. 사용 방법은 다음과 같습니다:

{% set dql_data = DQL("실행할 DQL 문") %}

특정 필드: {{ dql_data.some_field }}

내장 DQL 쿼리 예시¶

다음 내장 DQL 문은 host 필드가 "my_server"인 데이터를 조회하고, 첫 번째 데이터를 dql_data 변수에 할당합니다:

{% set dql_data = DQL("O::HOST:(host, host_ip, os, datakit_ver) { host = 'my_server' }") %}

호스트 OS: {{ dql_data.os }}

이후의 템플릿에서는 {{ dql_data.os }}를 사용하여 쿼리 결과의 특정 필드를 출력할 수 있습니다.

내장 DQL에 매개변수 전달¶

때로는 DQL 문을 실행하기 위해 매개변수를 전달해야 합니다. 이러한 매개변수는 DQL 문에 직접 내장될 수 있으며, by 필터를 추가할지 선택할 수 있습니다. 그러나 작성 방식이 약간 다릅니다. 일반적으로 변수를 참조할 때는 {{df_status}}를 사용합니다. 그러나 DQL 문에서는 {{ }}를 추가하지 않고 변수명을 직접 사용해야 하므로, 최종 작성 방식은 status입니다.

모니터 by에 region과 host가 구성되어 있고, 이벤트 내용 템플릿이 다음과 같다고 가정합니다:

{% set dql_data = DQL("O::HOST:(host_ip, os) { region = ?, host = ? }", region, host) %}

호스트 정보:
IP: {{ dql_data.host_ip }}
OS: {{ dql_data.os }}

이벤트에는 서로 다른 데이터를 표시하기 위한 region 및 host 템플릿 변수만 포함되어 있고, IP 주소, 운영 체제 등의 추가 정보는 포함되어 있지 않습니다.

그러면 내장 DQL을 사용하여 region과 host를 DQL 쿼리 매개변수로 사용하여 해당 데이터를 가져오고, {{ dql_data.host_ip }} 등을 사용하여 관련 정보를 출력할 수 있습니다.

내장 DQL 쿼리 함수 세부 사항¶

내장 DQL 쿼리 함수 호출 형식은 다음과 같습니다:

DQL(dql, param_1, param_2, ...)

첫 번째 매개변수는 DQL 문이며, 매개변수 자리 표시자 ?를 포함할 수 있습니다.
이후 매개변수는 DQL 문의 매개변수 값 또는 변수입니다.

매개변수 자리 표시자 ?는 특정 값으로 대체될 때 시스템에서 자동으로 이스케이프 처리됩니다.

host 변수 값이 "my_server"라고 가정하면, 내장 DQL 함수와 실행되는 최종 DQL 문은 다음과 같습니다:

DQL("O::HOST:(host, host_ip, os, datakit_ver) { host = ? }",  host)

O::HOST:(host, host_ip, os, datakit_ver) { host = 'my_server' }