본문으로 건너뛰기

Query Manager

검색된 문서들을 기반으로 exemONE의 Query Manager 기능을 상세히 설명드리겠습니다.

exemONE Query Manager 기능 상세 설명

1. 기능 개요​

메뉴 경로: Performance Analysis > Tool > Query Manager

Query Manager는 요건에 맞는 쿼리를 직접 작성하여 exemONE 수집 DB(ClickHouse / PostgreSQL)에 조회하는 도구입니다. 작성한 쿼리를 저장하고, 대시보드 위젯 지표, 알람(Alert), 알림(Notification) 파라미터 등에 활용할 수 있습니다.

2. 지원 버전 및 사전 조건​

지원 버전​

항목버전
Query Manager (PostgreSQL 지원)exemone-api v3.0.508.27 이상
지표 변수 설정(Set Stat Variable)Front v3.0.508.137 이상
알람 지표 등록exemone-front v3.0.508.32 / exemone-api v3.0.508.* / exemone-alerter v3.0.508.11 이상
Notification 파라미터 사용exemone-api v3.0.508.51 / exemone-front v3.0.508.39 등

3. DB 연결 설정 (사전 설정)​

Query Manager에서 데이터를 조회할 DB를 설정해야 합니다. exemONE의 Repository DB인 ClickHouse와 PostgreSQL 모두 지원합니다.

바이너리(Binary) 설치 환경에서 설정​

파일 위치: {EXEM_HOME}/services/exemone-api/configs/application.yml

spring:
  ...
  query-manager:
    # ClickHouse 설정
    clickhouse:
      url: jdbc:clickhouse://127.0.0.1:8123/default?max_execution_time=60
      username: exemone
      password: B5ICGPmyoO16xR4SzJJnYLYb7oMm1Gvd3s4I5ugY/R0=  # 사용자 비밀번호
      max-timeout: 60000
      max-connection-pool: 15

    # PostgreSQL 설정
    postgresql:
      url: jdbc:postgresql://127.0.0.1:5432/postgres
      username: postgres
      password: B5ICGPmyoO16xR4SzJJnYLYb7oMm1Gvd3s4I5ugY/R0=  # 사용자 비밀번호
      max-timeout: 60000
      max-connection-pool: 15
      schema: public  # 쿼리매니저 pg는 스키마 하나로 고정. 없으면 public 스키마 사용

주의 사항:

  • exemone-api v3.0.508.27 미만 버전으로 운영 중이었을 경우, 기존 spring.query-manager-datasource 항목을 삭제 후 위 내용으로 교체해야 합니다.
  • yaml 파일 작성 시 들여쓰기 및 띄어쓰기를 주의해야 합니다.

도커(Docker) 설치 환경에서 설정​

파일 위치: {EXEMONE_HOME}/containers/exemone-api/configs/application.yml

동일한 query-manager 항목을 추가합니다.

4. 화면 구성 상세​

메뉴 경로: Performance Analysis > Tool > Query Manager

순번항목내용
1New Query새 쿼리를 작성합니다.
2Select Database쿼리를 조회할 데이터베이스를 선택합니다. (ClickHouse / PostgreSQL)
3Query List저장된 쿼리 목록입니다.
4Creator / Last Modified ByCreator: 쿼리를 만든 사용자 정보
Last Modified By: 최근에 쿼리를 수정한 사용자 정보
5ButtonSave: 쿼리를 저장합니다.
Save As…: 쿼리를 다른 이름으로 저장합니다.
Reset: 작성한 쿼리를 초기화합니다.
6Query쿼리를 입력합니다.
7Set Stat Variable지표 변수를 추가합니다. (대시보드/알람 연계 시 필요)
8Collection쿼리 실행 결과입니다.

5. 사용 방법 (단계별)​

Step 1. 쿼리 작성​

  • New Query 버튼 클릭 후 쿼리를 작성합니다.
  • 변수 설정이 필요한 경우 '지표 변수 설정(Set Stat Variable)' 활성화 후 변수를 설정하여 쿼리에 적용합니다.
  • 쿼리 실행 결과를 확인합니다. 에러 발생 시 저장이 불가합니다.

중요: metrics, current 유형은 쿼리 결과 alias에 time, value 가 필수입니다.

Step 2. 쿼리 저장​

  • 대시보드에서 쿼리 매니저 사용이 필요한 경우, 쿼리 저장 시 '쿼리 공유' 활성화 후 데이터 ID, 데이터 타입을 지정하여 저장합니다.

Step 3. 대시보드 설정​

저장된 Query Manager 지표를 대시보드 위젯에 적용합니다.

6. 지표 변수 설정 (Set Stat Variable) 상세​

지원 버전: Front v3.0.508.137 이상

Metric 타입​

항목설명
적용 가능한 차트 타입타임시리즈
필수 Select 필드time (위젯 x축 시간값), value (위젯 y축 값), target_id (대상 id)
예약 변수fromTime: 데이터 조회 시작 시간
toTime: 데이터 조회 종료 시간
targetIds: 범례 위젯에 필터된 대상 태그 바인딩용 변수 (범례 위젯 사용 시 필수)

Metric 타입 샘플 쿼리:

-- fromTime ~ toTime 사이에 5초 틱을 가지는 'host_stat_active_memory_usage' 지표 metric
select target_id,
       toStartOfInterval(collect_time, INTERVAL '5 s') as time,
       argMax(value, collect_time) as value
from metric_dist
where data_id like 'host_stat_active_memory_usage'
  and collect_time >= fromTime and collect_time < toTime
  and target_id in ($_get_targets_from_tags('host', targetIds))
group by target_id, time

7. Query Manager History (실행 이력)​

메뉴 경로: Performance Analysis > Tool > Query Manager > History

순번항목내용
1Global Time실시간을 포함한 최근 쿼리 데이터를 보여줍니다. Default 최근 10분 데이터를 보여줍니다.
2Search쿼리를 검색합니다.
3Query Run History쿼리 실행 이력입니다.
4Option클릭 시 Grid의 옵션을 보여줍니다.
5Pagination페이지 이동

Query Run History Grid 컬럼:

순번항목내용
1Query쿼리 이름 (클릭 시 Query Manager Detail Slide로 이동)
2Start Time쿼리 실행 시각
3DB쿼리가 실행된 데이터베이스
4Target타겟 인스턴스
5Performer쿼리를 실행한 사용자
6Execution Time (sec)쿼리 수행 시간
7Error발생 에러 (클릭 시 Detail Slide로 이동)

8. Query Manager Detail Slide (이력 상세)​

History 화면에서 쿼리 클릭 시 상세 슬라이드가 열립니다.

순번항목내용
1Query실행된 쿼리입니다.
2Slide History이전 슬라이드 이력
3Close클릭 시 Detail Slide가 닫힙니다.
4Copy쿼리를 복사합니다.
5Information실행된 쿼리 정보입니다.

9. 대시보드 위젯 연계 (Custom Stat)​

메뉴 경로: Dashboard > 위젯 > 지표 설정 > Custom > Common

9-1. 위젯 지표 설정​

  1. 대시보드 위젯에서 커스텀 지표를 설정합니다.
  2. custom > common 목록에서 지표가 확인되지 않는 경우, 쿼리 매니저에서 설정한 데이터 타입을 확인 후 해당 데이터 타입 유형으로 설정합니다.

9-2. 글로벌 변수로 타겟 설정​

쿼리매니저 구문에 target_id 변수를 아래처럼 설정합니다:

target_id in ($_get_targets_from_tags('pod', targetIds))
  • 'pod': 해당 Target의 tag 값
  • 'targetIds': 지표 변수 이름

이후 대시보드 > 글로벌 변수 설정 후, 위젯의 변수 설정에서 글로벌 변수를 연결합니다.

9-3. 범례(Legend) 적용​

범례 위젯 사용 시 targetIds 예약어가 필수 추가되어야 하며, Query Manager key 값이 targetIds로 들어와야 합니다.

10. 알람(Alert) 지표 연계​

지원 버전: exemone-front v3.0.508.32, exemone-alerter v3.0.508.11 이상

주의: ClickHouse Repository에서 조회한 데이터만 알람으로 등록 가능합니다. PostgreSQL은 Alert 설정 불가.

알람 등록 절차​

Step 1. Performance Analysis > Query Manager에서 지표를 생성합니다.

Step 2. Select 데이터 조회 컬럼에 target_id 포함 (필수)

Step 3. 참조 변수 적용 (필수)

변수설명
fromTimeAlert 적용 시, 집계 범위 시작 시간
toTimeAlert 적용 시, 집계 범위 종료 시간
targetIdsAlert 적용 시, 타겟 설정 (태그 사용 필수)

11. Notification 파라미터 연계​

지원 버전: exemone-api v3.0.508.51, exemone-alerter v3.0.508.18 이상

Query Manager에서 등록한 지표를 알람 발생 시 Notification의 파라미터로 사용할 수 있습니다.

제약 사항:

  • fixed_contents 영역에 파라미터로 사용 시 적용 가능
  • 적용 가능한 알림 유형: 이메일, 슬랙, 텔레그램, 웹훅, 온사이트

Notification 파라미터 설정 절차​

Step 1. Performance Analysis > Query Manager에서 지표를 생성합니다.

  • 데이터 조회 결과 첫 번째 컬럼의 첫 번째 Row가 Parameter의 데이터로 전송됩니다.

Step 2. Query Manager 지표 저장 시 data_id를 별도로 저장합니다. (Notification에서 파라미터 입력 시 사용)

12. 커스텀 지표 미지원 위젯 목록​

아래 위젯 유형은 Query Manager 연계 커스텀 지표를 지원하지 않습니다:

  • Gauge
  • Action View
  • Heat map
  • Daily Comparison
  • Architecture 내 모든 Chart Type
  • Business 내 모든 Chart Type

13. 기능 요약 및 메뉴 경로 정리​

기능메뉴 경로
Query Manager 기본 화면Performance Analysis > Tool > Query Manager
실행 이력 확인Performance Analysis > Tool > Query Manager > History
DB 연결 설정 (바이너리){EXEM_HOME}/services/exemone-api/configs/application.yml
DB 연결 설정 (도커){EXEMONE_HOME}/containers/exemone-api/configs/application.yml
대시보드 위젯 연계Dashboard > 위젯 > Custom > Common
알람 지표 등록Setting > Alert > User Alert > Create Rule
Notification 파라미터 연계Setting > Alert > Notification > Add/Edit Notification

참고 문서 URL​