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

템플릿 문법을 통해 이벤트 알림 내용을 다음과 같이 사용자 정의할 수 있습니다.

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

템플릿 검증 및 미리보기¶

모니터의 이벤트 내용, 데이터 단절 이벤트 내용, 지능형 모니터의 이벤트 내용은 문법 검증을 지원합니다. 편집 후 입력란 밖으로 이동하거나 모니터를 저장하면 시스템이 템플릿을 검사하고 문법 문제를 표시합니다.

문법 검사를 통과한 후 이벤트 내용 편집기의 미리보기 버튼을 클릭하고, 필요에 따라 변수 테스트 값을 입력한 다음 미리보기를 클릭하여 렌더링 결과를 확인합니다. 일반 모니터는 현재 제목과 내용을 함께 미리보기하며, 지능형 모니터는 이벤트 내용을 미리보기합니다. df_status 등 변수의 테스트 값을 전환하여 이상, 복구 등의 조건 분기를 확인할 수 있습니다.

미리보기는 템플릿 효과를 확인하기 위한 것이며, 실제 알림은 이벤트 발생 시점의 데이터를 기준으로 합니다. 템플릿에 인라인 DQL이 포함된 경우, 미리보기는 현재 워크스페이스의 관련 데이터를 읽어옵니다.

기본 템플릿 변수¶

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

템플릿 변수 예시¶

모니터의 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)

특수 시나리오 변수¶

사용자 액세스 메트릭 탐지¶

사용자 액세스 메트릭 탐지에서는 위의 공통 템플릿 변수 외에도 다음 템플릿 변수를 추가로 지원합니다.

특수 문자 필드 처리¶

탐지 구성의 차원 필드에 특수 문자(예: -, @)가 포함된 경우(예: host-name, @level) 일반 변수 이름으로 직접 사용할 수 없으며, 템플릿 렌더링이 실패하게 됩니다.

해결 방법은 다음 형식으로 참조하는 것입니다.

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

템플릿 함수¶

이벤트의 필드 값을 직접 표시할 수 있을 뿐만 아니라, 템플릿 함수를 사용하여 필드 값을 추가로 처리하고 출력을 최적화할 수 있습니다.

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

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

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

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

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

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

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

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

템플릿 함수 예시¶

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

구성된 모니터의 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' }

DQL 문서 더 보기¶