사용자 정의 이벤트 알림 템플릿¶
템플릿 구문을 통해 이벤트 알림 내용을 사용자 정의할 수 있습니다:
-
동적 렌더링: {{ 필드 이름 }}을 사용하여 알림 필드를 직접 삽입합니다(예: {{ host }}, {{ df_status }}).
-
데이터 처리: {{ 변수 | 함수() }}를 통해 데이터를 형식화합니다(예: 타임스탬프를 날짜로, 숫자를 백분율로 변환).
-
조건 분기: {% if ... %}를 사용하여 상태별로 차별화된 알림을 구현합니다.
-
실시간 쿼리: DQL("쿼리 문")을 내장하여 연관 데이터(예: 호스트 IP, 애플리케이션 정보)를 가져옵니다.
템플릿 검증 및 미리보기¶
모니터의 이벤트 내용, 데이터 공백 이벤트 내용 및 지능형 모니터의 이벤트 내용은 구문 검증을 지원합니다. 편집 후 입력 상자 밖으로 이동하거나 모니터를 저장하면 시스템이 템플릿을 검사하고 구문 문제를 표시합니다.
구문 검사가 통과되면 이벤트 내용 편집기의 미리보기 버튼을 클릭하고, 필요에 따라 변수 테스트 값을 입력한 뒤 미리보기를 클릭하여 렌더링 결과를 확인합니다. 일반 모니터는 현재 제목과 내용을 함께 미리 보여주고, 지능형 모니터는 이벤트 내용을 미리 봅니다. df_status 등 변수의 테스트 값을 전환하여 이상, 복구 등 조건 분기를 확인할 수 있습니다.
미리보기는 템플릿 효과를 확인하기 위한 것이며, 실제 알림은 이벤트 발생 시점의 데이터를 기준으로 합니다. 템플릿에 내장 DQL이 포함된 경우 미리보기는 현재 워크스페이스의 관련 데이터를 읽습니다.
기본 템플릿 변수¶
템플릿 변수의 기본 구문은 {{ 필드 이름 }}이며, 이벤트 관련 동적 정보를 렌더링하는 데 사용할 수 있습니다. 다음은 일반적인 템플릿 변수와 그 용도입니다:
| 템플릿 변수 | 유형 | 설명 |
|---|---|---|
date, timestamp |
Integer | 이벤트 발생 시간. 단위는 초 |
df_date_range |
Integer | 시간 범위. 단위는 초 |
df_check_range_start |
Integer | 감지 범위 시작 시간. Unix 타임스탬프, 단위는 초 |
df_check_range_end |
Integer | 감지 범위 종료 시간. Unix 타임스탬프, 단위는 초 |
df_status |
String(Enum) | 모니터 이벤트의 일반적인 상태: 치명적 fatal심각 critical중요 error경고 warning정보 info정상 ok데이터 공백 nodata. 전체 값은 이벤트 필드 참조를 참조하고, 레벨 대응 관계는 이벤트 레벨을 참조하세요 |
df_event_id |
String | 이벤트 고유 ID |
df_event_link |
String | 이벤트 상세 페이지 링크 주소 |
df_dimension_tags |
String | 이벤트 차원. 감지 대상 식별에 사용됩니다 예: {"host":"web-001"} |
df_monitor_id |
String | 알림 정책 ID |
df_monitor_name |
String | 알림 정책 이름 |
df_monitor_checker_id |
String | 모니터 ID |
df_monitor_checker_name |
String | 모니터 이름 |
df_monitor_checker_value |
String | 감지 값, 즉 모니터가 감지한 값 ❗️감지 값은 호환성을 보장하기 위해 String 타입으로 강제 변환됩니다 |
df_monitor_checker_event_ref |
String | 모니터 이벤트 연관. 모니터 ID와 이벤트 df_dimension_tags를 기준으로 계산됩니다 |
df_fault_id |
String | 이번 장애 ID. 최초 장애 이벤트의 df_event_id 값입니다 |
df_fault_status |
String(Enum) | 이번 장애 상태. df_status의 중복 필드입니다. 가능한 값:okfault |
df_fault_start_time |
Integer | 이번 장애 발생 시간. Unix 타임스탬프, 단위는 초 |
df_fault_duration |
Integer | 이번 장애 지속 시간. 단위는 초 |
df_user_id |
String | 수동 복구 시 작업자 사용자 ID |
df_user_name |
String | 수동 복구 시 작업자 사용자 이름 |
df_user_email |
String | 수동 복구 시 작업자 사용자 이메일 |
df_crontab_exec_mode |
String(Enum) | 모니터 실행 모드, 가능한 값:crontabmanual |
df_site_name |
String | 현재 Guance 노드 이름 |
df_workspace_name |
String | 소속 워크스페이스 이름 |
df_workspace_uuid |
String | 소속 워크스페이스 ID |
df_label |
List | 모니터 태그 목록 |
df_check_condition |
Dict | 충족된 감지 조건 |
df_check_detail |
Dict | 변동 감지에 적용되며, 변동 비교 원본 값을 나타냅니다. 세 가지 필드를 포함합니다:change_value)comparison_value)detection_value) |
df_check_condition.operator |
String | 감지 조건을 충족한 연산자, 예: >, >= 등 |
df_check_condition.operands |
List | 감지 조건을 충족한 피연산자 목록. 일반적으로 피연산자는 1개이지만 between 등 연산자는 피연산자가 2개입니다 |
df_check_condition.operands[#] |
Integer, Float | 감지 조건을 충족한 피연산자 |
Result |
Integer, Float | 감지된 값. df_monitor_checker_value와 마찬가지로 감지 시 생성된 값이지만, 필드 타입은 감지 당시의 원시 타입이며 String으로 강제 변환되지 않습니다 |
df_dimension_tags의 각 필드 |
String | df_dimension_tags의 각 필드가 추출됩니다 |
df_event |
Dict | 전체 이벤트 데이터 |
df_studio_env_name |
현재 환경 이름 | |
df_studio_console_base_url |
현재 환경 콘솔 주소 | |
df_studio_monitor_base_link |
현재 환경 모니터 주소 |
템플릿 변수 예시¶
모니터 by에 region 및 host가 구성되어 있고 이벤트 내용 템플릿이 다음과 같다고 가정합니다:
이벤트 이름:
이벤트 내용:
- 지역: {{ region }}
- 호스트: {{ host }}
- 레벨: {{ df_status }}
- 감지 값: {{ Result }}
- 모니터: {{ df_monitor_checker_name }} (알림 정책: {{ df_monitor_name }})
그러면 error 이벤트가 발생한 후 렌더링된 이벤트 출력은 다음과 같습니다:
출력 이벤트 이름:
출력 이벤트 내용:
특수 시나리오 변수¶
RUM 지표 감지¶
RUM 지표 감지에서는 위의 공통 템플릿 변수 외에 다음 템플릿 변수를 추가로 지원합니다:
| 템플릿 변수 | 유형 | 설명 |
|---|---|---|
app_id |
String | 애플리케이션 ID |
app_name |
String | 애플리케이션 이름 |
app_type |
String | 애플리케이션 유형 |
특수 문자 필드 처리¶
감지 구성의 차원 필드에 특수 문자(예: -, @)가 포함된 경우(예: host-name, @level) 일반 변수 이름으로 직접 사용할 수 없으며 템플릿 렌더링이 실패합니다.
해결 방법은 다음 형식으로 참조하는 것입니다:
-
{{ host-name }}대신{{ df_event['host-name'] }}를 사용합니다. -
{{ @level }}대신{{ df_event['@level'] }}를 사용합니다.
템플릿 함수¶
이벤트의 필드 값을 직접 표시하는 것 외에도 템플릿 함수를 사용하여 필드 값을 추가 처리하고 출력을 최적화할 수 있습니다.
기본 구문은 다음과 같습니다:
구체적인 예시는 다음과 같습니다:
템플릿 함수에 매개변수를 전달해야 하는 경우 구문은 다음과 같습니다:
Warning
템플릿 함수를 사용하기 전에 템플릿 변수에 연산을 적용해야 하는 경우 괄호를 추가하는 것을 잊지 마세요. 예:
사용 가능한 템플릿 함수 목록은 다음과 같습니다:
| 템플릿 함수 | 매개변수 | 설명 |
|---|---|---|
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 }}출력: 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_dimension_tags | to_pretty_tags }}
- 시간: {{ date | to_datetime }}
- 레벨: {{ df_status | to_status_human }}
- 감지 값: {{ (Result * 100) | to_round(2) }}
그러면 error 이벤트가 발생한 후 렌더링된 이벤트 출력은 다음과 같습니다:
출력 이벤트 이름:
출력 이벤트 내용:
템플릿 분기¶
템플릿은 조건에 따라 다른 내용을 렌더링하는 분기 구문도 지원합니다.
템플릿 분기 예시¶
다음 예시는 fatal 치명적 알림을 별도로 처리하고 ok일 때만 복구 정보를 출력합니다. 나열되지 않은 상태는 원시 값을 표시하여 다른 이벤트를 정상으로 잘못 판단하지 않도록 합니다:
{% if df_status == 'fatal' %}
치명적인 문제입니다. 즉시 처리하세요!
{% elif df_status == 'critical' %}
심각한 문제입니다. 즉시 처리하세요!
{% elif df_status == 'error' %}
중요한 문제입니다. 처리하세요
{% elif df_status == 'warning' %}
경고 이벤트입니다. 주의하세요
{% elif df_status == 'nodata' %}
데이터 공백입니다. 데이터 보고 상태를 확인하세요
{% elif df_status == 'info' %}
정보 이벤트입니다. 필요에 따라 확인하세요
{% elif df_status == 'ok' %}
정상으로 복구되었습니다
{% else %}
현재 이벤트 상태: {{ df_status }}. 이벤트 상세를 확인하세요
{% endif %}
더 일반적인 예시는 다음과 같습니다:
{% if df_status != 'ok' %}
> 레벨: {{ df_status }}
> 호스트: {{ host }}
> 내용: Elasticsearch JVM 힙 메모리 사용량이 {{ Result }}%입니다
> 권장 사항: 현재 JVM 가비지 수집이 JVM 가비지 생성 속도를 따라가지 못하고 있으니 비즈니스 상태를 즉시 확인하세요
{% else %}
> 레벨: {{df_status}}
> 호스트: {{host}}
> 내용: Elasticsearch JVM 힙 메모리 알림이 복구되었습니다
{% endif %}
내장 DQL 쿼리 함수¶
일부 경우에는 템플릿 변수만으로 렌더링 요구 사항을 충족할 수 없습니다. 이때 내장 DQL 쿼리 함수를 사용하여 추가 데이터 쿼리를 수행할 수 있습니다.
내장 DQL 쿼리 함수는 현재 워크스페이스에서 이번 감지 시간 범위 내에 임의의 DQL 문을 실행할 수 있습니다. 일반적으로 쿼리 결과의 첫 번째 데이터는 템플릿에서 템플릿 변수로 사용할 수 있으며, 사용 방법은 다음과 같습니다:
내장 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 문의 매개변수 값 또는 변수입니다.
매개변수 자리표시자 ?가 구체적인 값으로 대체될 때 시스템이 자동으로 이스케이프합니다.
변수 host의 값이 "my_server"라고 가정하면 내장 DQL 함수와 실행되는 최종 DQL 문은 다음과 같습니다:
Warning
- 내장 DQL 쿼리는 템플릿 시작 부분에 배치해야 합니다.
- 쿼리 결과 이름(여기서는
dql_data)은 일반 프로그래밍 언어의 명명 요구 사항을 따르며, 임의의 영문자로 시작하고 영문자, 숫자, 밑줄만 포함하는 문자열이어야 합니다. emoji 사용은 권장하지 않습니다. - 쿼리 결과 이름은 기존의 모든 템플릿 변수, 템플릿 함수와 중복되지 않아야 합니다. 그렇지 않으면 예기치 않은 문제가 발생할 수 있습니다.
- DQL에서 필드에 함수를 사용한 경우 이후 사용을 쉽게 하기 위해
AS로 필드에 별칭을 지정하는 것이 좋습니다(예:O::HOST:( last(host) AS last_host )). - DQL의 필드 이름에 특수 문자가 포함된 경우 템플릿 변수와 마찬가지로
{{ dql_data['host-name'] }},{{ dql_data['@level'] }}를 사용하여 렌더링해야 합니다.