룩업(Lookup) 생성·활용 가이드

How To
1

본 문서는 로그프레소 룩업을 만들고, 다양한 방법으로 데이터를 채워 조회에 활용하는 절차를 정리한 가이드입니다.
명령어/경로는 실제 환경에 맞게 반드시 교체하세요.

개요

  • 룩업(Lookup) 은 쿼리를 실행하면서 수시로 조회하는 참조 데이터를 관리하는 테이블입니다.
  • 임직원 목록, 자산 정보(IP↔호스트명↔부서), 우편번호, 국가 코드처럼 로그에 살을 붙이는 용도로 자주 사용합니다.
  • 룩업을 채우는 방법은 수동 생성(직접 입력·CSV 업로드)과 자동 생성(쿼리 결과 적재·REST API)으로 나뉘며, 목적에 맞는 방식을 선택합니다.

적용 대상

  • 제품: Logpresso Sonar
  • 버전:
    • 테스트 버전: SNR-5.0.2605.1
    • 실험실 앱 버전: 2.0.2607.0 (sonar-insert-lookup-records 사용 시 필요)
  • 대상 환경:
    • 웹 콘솔 접근이 가능한 로그프레소 운영 환경
    • sonar-insert-lookup-records 사용 시 실험실(Lab) 앱 설치 필요

1. 룩업 만들기 — 스키마 정의

레코드를 채우는 방식과 관계없이, 먼저 룩업의 틀(스키마) 을 만들어야 합니다.
스키마는 생성 후 수정할 수 없습니다. 키 필드와 필드 구성을 처음에 신중히 정하세요. 구조를 바꾸려면 삭제 후 다시 만들어야 합니다.

경로 : 웹 콘솔 → 분석 → 룩업 → 추가

  1. 기본 속성 — 이름, 설명을 입력합니다.
  2. 스키마 설정 — 새 필드 버튼으로 필드를 추가합니다. (최대 40개)
    • 첫 번째 필드가 키 필드입니다. (조회의 기준이 되는 열)
    • 각 필드마다 이름 · 길이 · 빈 값 허용 여부를 지정합니다.
  3. 저장을 누릅니다.

필드 제약

항목 제약
키 필드 길이 최대 255자 (빈 값 불가, 필수)
기타 필드 길이 최대 2,000자 (전체 필드 길이 합 50,000자 이내)
예약어(필드명 사용 불가) created, created_at, updated, updated_at

예시 스키마 (자산 룩업 ip_asset)

필드 역할 빈 값
ip 키 필드 불가
hostname 값 허용
dept 값 허용

2. 수동 생성 ① — 레코드 직접 입력

레코드 건수가 적을 때 웹 콘솔에서 직접 입력합니다.
경로 : 룩업 선택 → 데이터 화면

단건 입력

  1. 새 레코드 클릭
  2. 각 필드 값 입력 → 추가
    • 스키마(길이·빈 값·키 중복 등) 위반 시 오류 메시지가 표시됩니다.

일괄 입력 (Excel 붙여넣기)

  1. 일괄 입력 클릭 → 편집 모드 진입
  2. 셀에 직접 입력하거나 Excel·Google Sheets에서 복사한 표를 그대로 붙여넣기 (한 번에 최대 1,000건)
  3. 오류 셀은 붉게 표시됩니다. (셀에 마우스를 올리면 사유 확인)
  4. 저장

3. 수동 생성 ② — CSV 파일 업로드

이미 정리된 CSV가 있거나, 대량 레코드를 파일로 관리할 때 사용합니다.
경로 : 룩업 데이터 화면 → 업로드

  1. 업로드 클릭 → 룩업 파일 업로드 대화상자
  2. CSV 파일 선택 + 인코딩 선택 (UTF-8 / UTF-16 BE / 확장완성형)
  3. 자동 검증 후 적재 (오류가 하나라도 있으면 전체가 저장되지 않음)

CSV 파일 요건

요건 내용
첫 행(헤더) 스키마에 정의한 모든 필드명 포함 (순서는 무관)
키 필드 반드시 값이 있어야 함
각 필드 스키마 제약(길이·빈 값 허용 여부) 준수

CSV 예시 (ip_asset.csv)

ip,hostname,dept
192.0.2.1,web01,영업팀
192.0.2.2,db01,개발팀

4. 자동 생성 — 조회 결과를 룩업에 바로 등록 : sonar-insert-lookup-records

쿼리 파이프라인을 통과한 레코드를 그대로 룩업에 적재하는 방법입니다.

CSV 파일을 거치지 않고 조회 → 룩업 등록을 한 번에 처리하므로, “조회한 결과를 바로 룩업으로” 하려는 목적에 가장 적합합니다.
sonar-insert-lookup-records는 실험실(Lab) 앱 명령어입니다. 먼저 로그프레소 스토어에서 해당 실험실 앱을 설치해야 사용할 수 있습니다.

쿼리 작성 후, 예약 쿼리(스케줄) 로 등록하면, 조회 결과를 주기적으로 룩업에 자동 반영할 수 있습니다.

문법

sonar-insert-lookup-records lookup=LOOKUP [update-fields=UPDATE-FIELDS]
옵션 설명
lookup=LOOKUP 레코드를 적재할 대상 룩업 이름 (1번에서 미리 생성)
update-fields=UPDATE-FIELDS (선택) 키가 이미 존재할 때 갱신할 필드 목록. 지정하면 신규 키는 추가하고 기존 키는 해당 필드만 갱신(upsert)합니다. 생략하면 신규 레코드 추가로 동작합니다.

① 조회 결과를 룩업에 등록 (예: 단건 샘플로 즉시 실행)

json "{'ip':'192.0.2.1', 'hostname':'web01', 'dept':'영업팀'}"
| sonar-insert-lookup-records lookup=ip_asset
  • 입력 레코드의 필드(ip, hostname, dept)가 ip_asset 룩업의 동일한 이름의 필드로 매핑되어 저장됩니다.
  • 실제로는 table ...이나 stats ... 등의 조회·집계 결과를 파이프로 넘겨 대량 등록합니다.

② 기존 레코드 갱신 (upsert)

json "{'ip':'192.0.2.1', 'hostname':'web01', 'dept':'인프라팀'}"
| sonar-insert-lookup-records lookup=ip_asset update-fields=dept
  • 키(ip=192.0.2.1)가 이미 있으면 dept 필드만 인프라팀으로 갱신합니다.

5. 자동 생성 — REST API로 등록·갱신

REST API로도 룩업을 생성하고 조회 결과를 레코드로 등록·갱신할 수 있습니다.
참고 문서 : 로그프레소 API 사용 가이드

참고 : 로그프레소 소나 REST API 레퍼런스 문서의 룩업 API 절 (/api/sonar/lookups, /api/sonar/lookups/:guid/records)

6. 룩업 조회·활용 : lookup · lookuptable

lookup — 레코드마다 키로 조회해 값을 붙이기

lookup TABLE SRC_FIELD [as LOOKUP_KEY] output FIELD [as ALIAS], ...

json "{'src_ip':'192.0.2.1'}"
| lookup ip_asset src_ip as ip output hostname, dept
  • 입력 레코드의 src_ip 값으로 ip_asset 룩업을 조회해 hostname·dept를 붙입니다.
  • src_ip as ip — 입력 필드명(src_ip)과 룩업 키 필드명(ip)이 다르면 as로 맞춰줍니다.
  • 키가 없으면 해당 출력 필드는 null이 됩니다. output hostname as src_host처럼 담을 필드명을 바꿀 수도 있습니다.

lookuptable — 룩업 전체 내용을 레코드로 펼쳐 보기

lookuptable ip_asset               # 전체 조회
lookuptable ip_asset limit=10      # 최대 10건
lookuptable ip_asset ip, hostname  # 특정 필드만

lookup은 입력 레코드의 키로 값을 조회하고, lookuptable은 룩업 자체를 통째로 출력한다는 점이 다릅니다. 룩업 내용 확인·검수에 lookuptable을 활용하세요.

참고 링크