sonar-ai-generate-parser

로그 샘플로부터 로그프레소 AI(sLLM)를 통해 정규표현식 파서를 자동으로 생성합니다. 서브쿼리로 수집한 원본 로그 표본을 sLLM에 전달해 패턴을 분석하고, 검증을 통과한 정규식을 새 파서로 등록하여 로그 정규화 작업을 단축합니다. 로그프레소 AI 어시스턴트 접속 프로파일은 사전에 구성되어 있어야 합니다.

명령어 속성

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

문법

sonar-ai-generate-parser [profile=STR] code=STR [prompt=STR] [max-retry=INT] [debug=BOOL] [dry-run=BOOL] [ SUBQUERY ]

옵션

profile=STR: 사용할 로그프레소 AI 어시스턴트 접속 프로파일 이름. 생략하면 사용 가능한 sLLM 프로파일을 자동으로 선택합니다.
code=STR: 생성할 파서의 식별자(1자 이상 50자 이하). 같은 식별자가 이미 존재하면 sLLM이 새 정규식을 추가 패턴으로 학습하는 기준으로 활용합니다.
prompt=STR: 파서 생성을 위한 추가 가이드 문구. 특정 필드 추출 의도, 도메인 맥락, 무시해야 할 토큰 등을 자연어로 전달합니다.
max-retry=INT: 정규식 검증에 실패했을 때 sLLM에 재요청을 시도하는 최대 횟수 (기본값: 3).
debug=BOOL: t로 지정하면 디버그 레벨 진행 메시지(level=debug)를 출력 행에 함께 반환합니다 (기본값: f).
dry-run=BOOL: t로 지정하면 정규식 생성 및 검증 과정만 수행하고 실제 파서는 등록하지 않습니다 (기본값: f).

대상

SUBQUERY: 로그 표본을 추출하기 위한 서브쿼리. 대괄호([ ]) 안에 작성하며, 서브쿼리 결과 행이 sLLM의 입력 표본으로 전달됩니다. 일반적으로 table 또는 logger 명령어로 원본 로그를 조회합니다.

출력 필드

필드	타입	설명
`_time`	날짜	진행 이벤트 발생 시각
`profile`	문자열	사용된 접속 프로파일 이름
`level`	문자열	메시지 레벨 (`info`, `debug`, `error`). `debug`는 `debug=t`일 때만 출력
`module`	문자열	메시지를 생성한 처리 모듈 이름
`msg`	문자열	진행 상황 또는 결과 메시지
`status`	문자열	처리 상태 (`success`, `failure`)
`error`	문자열	실패 시 오류 메시지. 실패한 단계에서만 채워집니다

오류 코드

파싱 오류

오류 코드	메시지	설명
212200	사용 가능한 SLLM 프로파일이 없습니다.	시스템에 등록된 sLLM 접속 프로파일이 하나도 없을 때 발생합니다.
212201	SLLM 프로파일 이름을 입력하세요.	`profile` 옵션을 생략했고 자동 선택할 sLLM 프로파일도 없을 때 발생합니다.
212202	하나의 프로파일만 지정하세요.	`profile` 옵션에 둘 이상의 프로파일이 매칭될 때 발생합니다.
212270	code 옵션을 지정하세요.	`code` 옵션이 누락되었거나 빈 문자열일 때 발생합니다.
212271	파서 식별자는 50자 이하여야 합니다.	`code` 옵션 값의 길이가 50자를 초과할 때 발생합니다.
212240	[ ] 괄호 안에 서브쿼리를 지정하세요.	명령어 뒤에 대괄호로 감싼 서브쿼리가 없거나 비어 있을 때 발생합니다.

런타임 오류

해당 사항 없음

파서 생성 단계에서 예외가 발생하면 명령어를 중단하지 않고 level=error, status=failure 행을 출력하여 실패 사유를 error 필드에 기록합니다.

설명

sonar-ai-generate-parser는 서브쿼리에서 추출한 로그 표본을 sLLM에 전달해 정규표현식 파서를 자동 생성하는 드라이버 쿼리입니다. 명령어 실행 흐름은 다음과 같습니다.

대괄호 안 서브쿼리를 실행해 로그 표본을 수집합니다.
표본과 prompt로 전달된 가이드를 sLLM에 보내 정규식 후보를 생성합니다.
생성된 정규식이 표본 로그를 안정적으로 파싱하는지 검증합니다.
검증에 실패하면 최대 max-retry 횟수까지 sLLM에 보정을 요청합니다.
검증을 통과하면 code로 지정한 식별자로 파서를 등록합니다. dry-run=t이면 등록 단계를 건너뜁니다.

각 단계의 진행 상황은 한 행씩 파이프라인에 푸시됩니다. level 필드로 단계 유형(info, debug, error)을 구분할 수 있고, 마지막 행은 일반적으로 status=success 또는 status=failure를 갖습니다.

profile 옵션에 지정한 접속 프로파일은 단일 프로파일이어야 하며, 와일드카드 등으로 여러 프로파일이 매칭되면 오류 코드 212202가 발생합니다. code 식별자는 1자 이상 50자 이하여야 하며, 이미 등록된 식별자를 지정하면 sLLM이 기존 패턴을 보완하는 방식으로 동작합니다.

본 명령어는 sLLM 호출에 의존하므로 동일한 입력에 대해서도 호출 시점이나 모델 응답에 따라 생성된 정규식이 달라질 수 있습니다. 결과 정규식은 등록 전에 표본 로그로 검증되지만, 운영 환경에 적용하기 전에 dry-run=t로 검증 결과를 확인하고 실제 로그 분포를 검토하는 것이 좋습니다. 표본 행 수가 너무 적거나 패턴 변동이 큰 경우 검증 실패와 재시도가 누적되어 응답 시간이 길어질 수 있습니다.

사용 예

Apache 접근 로그 표본으로 파서 생성
```
sonar-ai-generate-parser code="WEB_APACHE_AUTO" [
  table limit=200 WEB_APACHE_SAMPLE
  | fields line
]
```
WEB_APACHE_SAMPLE 테이블에서 200건의 원본 로그(line)를 표본으로 추출하여 WEB_APACHE_AUTO 식별자로 파서를 생성합니다. 진행 상황과 최종 등록 결과가 행으로 출력됩니다.
추가 가이드와 디버그 메시지 포함
```
sonar-ai-generate-parser code="WEB_APACHE_AUTO" prompt="src_ip, status, bytes 필드를 반드시 추출" debug=t [
  table limit=500 WEB_APACHE_SAMPLE
  | fields line
]
```
prompt로 추출 의도를 명시하고, debug=t로 sLLM 호출과 검증의 세부 단계 메시지(level=debug)도 함께 확인합니다.
시뮬레이션 모드로 검증만 수행
```
sonar-ai-generate-parser code="WEB_APACHE_AUTO" dry-run=t max-retry=5 [
  table limit=200 WEB_APACHE_SAMPLE
  | fields line
]
```
dry-run=t로 파서 등록 없이 정규식 생성과 검증만 수행하고, 검증 실패 시 최대 5회까지 sLLM에 재요청합니다. 실제 운영 적용 전에 결과를 확인할 때 사용합니다.

호환성

sonar-ai-generate-parser 명령어는 소나 5.0.2603.0 버전부터 사용 가능합니다.