evtctxadd

입력 데이터가 조건식과 일치하면 지정한 토픽과 키로 이벤트 컨텍스트를 생성합니다. 이미 동일한 키의 이벤트 컨텍스트가 존재하면 타임아웃을 연장합니다.

명령어 속성

항목	설명
명령어 유형	가공 쿼리
필요 권한	없음
라이선스 사용량	해당 없음
병렬 실행	지원
분산 실행	수집 노드에서 실행 (mapper)

문법

evtctxadd [topic=STR] [key=STR] [expire=INT{s|m|h|d|mon}] [timeout=INT{s|m|h|d|mon}] [maxrows=INT] [logtick=STR] [dynamic=BOOL] EXPR

옵션

topic=STR: 이벤트 토픽 이름. 다른 규칙의 이벤트와 구분되도록 유일한 이름을 부여합니다. dynamic=t인 경우 이 옵션은 무시됩니다.
key=STR: 이벤트 컨텍스트를 구분하는 키 값을 추출할 필드 이름. dynamic=t인 경우 이 옵션은 무시됩니다.
expire=INT{s|m|h|d|mon}: 만료 시간. 이벤트 컨텍스트 생성 시점부터 지정된 시간이 경과하면 이벤트 컨텍스트가 삭제됩니다. 조건식에 일치하는 입력 데이터가 추가로 들어와도 만료 시간은 연장되지 않습니다. dynamic=t인 경우 이 옵션은 무시됩니다.

s: 초
m: 분
h: 시
d: 일
mon: 월

timeout=INT{s|m|h|d|mon}: 타임아웃. 마지막으로 조건에 일치하는 이벤트를 수신한 시점부터 지정된 시간이 경과하면 이벤트 컨텍스트가 삭제됩니다. 조건식에 일치하는 입력 데이터가 추가로 들어오면 타임아웃이 연장됩니다. dynamic=t인 경우 이 옵션은 무시됩니다.

s: 초
m: 분
h: 시
d: 일
mon: 월

maxrows=INT: 이벤트 컨텍스트에 저장할 최대 행 수. dynamic=t인 경우 이 옵션은 무시됩니다. (기본값: 10)
logtick=STR: 외부 시계 호스트 필드 이름. 지정하면 입력 레코드의 해당 필드에서 호스트 이름을 추출하고, _time 필드의 시간을 기준으로 이벤트 시계를 진행합니다.
dynamic=BOOL: t로 지정하면 topic, key, expire, timeout, maxrows 값을 입력 레코드의 필드에서 가져옵니다. expire와 timeout 값은 초 단위의 자연수로 지정합니다.

대상

EXPR: 이벤트 컨텍스트를 생성할 조건식. 조건식의 평가 결과가 null이 아니고 false가 아닌 경우에 이벤트 컨텍스트를 생성합니다.

입력 필드

dynamic=t가 아닌 경우:

필드	타입	필수 여부	설명
`key` 옵션에 지정한 필드	모든 타입	필수	이벤트 컨텍스트 키 값. null이면 이벤트 컨텍스트를 생성하지 않습니다.

dynamic=t인 경우:

필드	타입	필수 여부	설명
`topic`	문자열	필수	이벤트 토픽 이름. null이거나 문자열이 아니면 `_error` 필드에 오류 메시지를 할당합니다.
`key`	모든 타입	필수	이벤트 컨텍스트 키 값. null이면 `_error` 필드에 오류 메시지를 할당합니다.
`expire`	숫자	선택	만료 시간 (초 단위). 0 이하이거나 숫자가 아니면 `_error` 필드에 오류 메시지를 할당합니다.
`timeout`	숫자	선택	타임아웃 (초 단위). 0 이하이거나 숫자가 아니면 `_error` 필드에 오류 메시지를 할당합니다.
`maxrows`	숫자	선택	최대 행 수. 0 미만이거나 숫자가 아니면 `_error` 필드에 오류 메시지를 할당합니다.

출력 필드

입력 레코드의 필드를 그대로 전달합니다. dynamic=t인 경우, 오류가 발생하면 다음 필드가 추가될 수 있습니다.

필드	타입	설명
`_error`	문자열	오류 메시지 (dynamic 모드 오류 발생 시)

오류 코드

파싱 오류

오류 코드	메시지	설명
23300	topic 옵션을 설정해주세요.	`dynamic=t`가 아닌데 `topic` 옵션이 없는 경우
23301	key 옵션을 설정해주세요.	`dynamic=t`가 아닌데 `key` 옵션이 없는 경우
23302	expire 값은 시간 범위 형식으로 지정해야 합니다. s(초), m(분), h(시), d(일), mon(월) 단위로 지정할 수 있습니다.	`expire` 값이 시간 범위 형식이 아닌 경우
23303	timeout 값은 시간 범위 형식으로 지정해야 합니다. s(초), m(분), h(시), d(일), mon(월) 단위로 지정할 수 있습니다.	`timeout` 값이 시간 범위 형식이 아닌 경우
23304	maxrows 값은 0 혹은 양의 정수를 지정해야 합니다.	`maxrows` 값이 0 미만이거나 정수가 아닌 경우
23305	evtctxadd 명령어를 실행할 조건식을 지정하십시오.	조건식이 지정되지 않은 경우

런타임 오류

해당 사항 없음

설명

evtctxadd 명령어는 입력 레코드를 순회하며, 각 레코드가 조건식과 일치하면 지정한 토픽과 키로 이벤트 컨텍스트를 생성하거나 갱신합니다. 이벤트 컨텍스트는 복합 이벤트 처리(CEP)를 위한 메모리 저장소에 보관됩니다.

이벤트 컨텍스트에는 만료 시간(expire)과 타임아웃(timeout)을 설정할 수 있습니다. 만료 시간은 이벤트 컨텍스트 생성 시점부터의 절대적인 수명으로, 조건에 일치하는 데이터가 추가로 들어와도 연장되지 않습니다. 반면 타임아웃은 마지막으로 조건에 일치하는 데이터를 수신한 시점부터 계산되므로, 새로운 데이터가 들어올 때마다 연장됩니다.

maxrows 옵션으로 이벤트 컨텍스트에 저장할 최대 행 수를 제한할 수 있습니다. 저장된 행은 이후 evtctxget() 함수로 조회할 수 있습니다.

dynamic=t 옵션을 사용하면 토픽, 키, 만료 시간, 타임아웃, 최대 행 수를 입력 레코드의 필드에서 동적으로 가져옵니다. 이 경우 topic, key, expire, timeout, maxrows 옵션은 무시됩니다. 동적 모드에서 필수 필드가 누락되거나 값이 유효하지 않으면 해당 레코드의 _error 필드에 오류 메시지를 할당하고 이벤트 컨텍스트를 생성하지 않습니다.

입력 레코드는 이벤트 컨텍스트 생성 여부와 관계없이 다음 명령어로 전달됩니다.

사용 예

이 사용 예에서 조회하는 WEB_APACHE_SAMPLE 테이블을 준비하려면 쿼리 실습용 데이터를 참고하세요.

동일 IP에서 반복 접근을 감지하는 이벤트 컨텍스트 생성
```
table duration=1h WEB_APACHE_SAMPLE
| evtctxadd topic=repeat_access key=src_ip expire=1h timeout=5m src_ip != null
```
src_ip를 키로 사용하여 반복 접근 이벤트 컨텍스트를 생성합니다. 만료 시간은 1시간이며, 마지막 접근 후 5분이 지나면 타임아웃으로 삭제됩니다.
오류 응답 이벤트 컨텍스트를 최대 행 수와 함께 생성
```
table duration=1h WEB_APACHE_SAMPLE
| evtctxadd topic=error_access key=src_ip expire=30m maxrows=50 status >= 400
```
HTTP 상태 코드가 400 이상인 오류 응답에서 src_ip를 키로 이벤트 컨텍스트를 생성하고, 최대 50개의 행을 저장합니다.
동적 모드로 이벤트 컨텍스트 생성
```
json "[{'topic': 'scan_detect', 'key': '192.0.2.1', 'expire': 3600, 'timeout': 600, 'src_ip': '192.0.2.1', 'status': 404}]"
| evtctxadd dynamic=t status == 404
```
입력 레코드의 topic, key, expire, timeout 필드 값을 사용하여 이벤트 컨텍스트를 동적으로 생성합니다. expire와 timeout 값은 초 단위입니다.

호환성

evtctxadd 명령어는 소나 4.0 이전 버전부터 제공되었습니다.