본문으로 건너뛰기

exemONE Query Manager

1. 개요​

메뉴 경로: Performance Analysis > Query Manager

요건에 맞는 쿼리를 직접 작성하여 exemONE 수집 DB(Clickhouse 또는 PostgreSQL)에서 데이터를 조회하고, 지표를 생성하여 대시보드·알람·알림에 활용할 수 있는 기능입니다.

전제 조건:

항목내용
지원 RepositoryClickhouse, PostgreSQL 모두 지원 (PostgreSQL 지원은 exemone-api v3.0.508.27 이상)
알람 지원 범위Clickhouse Repository 에서 조회한 데이터만 알람으로 등록 가능. PostgreSQL에서는 Alert 설정 불가
지표 변수 설정 지원 버전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 등

2. 기본 뷰 화면 설명​

2-1. Query Manager 화면 구성​

메뉴 경로: Performance Analysis > 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쿼리 실행 결과입니다.

2-2. Query Manager History 화면​

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

실행한 쿼리 과거 내역을 출력하는 화면입니다.

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

Query Run History Grid 항목:

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

2-3. Query Manager Detail Slide​

메뉴 경로: Performance Analysis > Query Manager > History > Query 클릭

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

3. 상세 기능 설명​

3-1. 쿼리 작성 및 실행​

메뉴 경로: Performance Analysis > Query Manager > Query 입력 영역

사용 방법:

단계설명
Step 1Performance Analysis > Query Manager 접속 후 [New Query] 버튼 클릭
Step 2Select Database에서 Clickhouse 또는 PostgreSQL 중 조회 대상 DB 선택
Step 3Query 입력 영역에 쿼리 작성
Step 4변수 설정이 필요한 경우 [Set Stat Variable] 활성화 후 변수 설정하여 쿼리에 적용
Step 5쿼리 실행 결과 확인. 에러 발생 시 저장 불가

3-2. 지표 변수 설정 (Set Stat Variable)​

메뉴 경로: Performance Analysis > Query Manager > Set Stat Variable

쿼리 지표가 설정된 위젯에서 동적으로 값을 참조하여 쿼리를 실행하기 위한 변수를 설정합니다.

지표 변수 예약어:

변수명설명
fromTime데이터 조회 시작 시간 / 알람 적용 시 집계 범위 시작 시간
toTime데이터 조회 종료 시간 / 알람 적용 시 집계 범위 종료 시간
targetIds범례 위젯에 필터된 대상 태그 바인딩용 변수 (범례 위젯 사용 시 필수) / 알람 적용 시 타겟 설정
clickedTime타임시리즈 차트에서 특정 시간을 클릭했을 때 해당 시간을 참조하는 변수 (트리그리드에서 사용)

쿼리 예약 함수:

함수설명
$_get_targets_from_tags({category}, {tag})target id 추출 함수. 대시보드 변수 필터 사용 시 반드시 사용. 사용자 권한에 포함된 대상만 필터됨

함수 파라미터:

파라미터설명
category (string)대상이 속하는 카테고리 (예: 'host', 'database', 'application' 등)
tag (string)target_id로 추출하고자 하는 대상 태그 (예: database;tag;*)

주의: {tag} 에는 target_id가 바인딩되어서는 안 되며, 대시보드 글로벌 변수 필터와 같은 태그를 지표 변수에 매핑해야 합니다.

3-3. 쿼리 저장 및 공유 (Save / Share Query)​

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

대시보드 위젯 또는 알람에서 쿼리 매니저를 사용하려면 저장 시 [Share Query] 옵션을 활성화하여 Data Setting을 지정해야 합니다.

Data Setting 항목:

항목설명
Share Query활성화 시 Data Setting 설정이 가능해집니다.
Data IDqm_{Data ID} 형식으로 exemONE Clickhouse DB의 xm_metric 테이블에 저장됩니다.
Data TypeMetric / Current / Scatter / Table 중 선택. Table 1개만 지정 시 Alert Data 토글이 활성화됩니다.
Alert Data활성화 시 알람으로 설정 가능합니다. (Clickhouse 조회 지표만 해당)

4. 지표 타입별 사용 방법​

4-1. Metric 타입​

적용 가능한 차트 타입: 타임시리즈(Timeseries)

Select 필드 필수 포함 항목:

필드명설명
time위젯 x축에 대응되는 시간값 (필수)
value위젯 y축에 대응되는 값 (필수)
target_id대상 id (필수)

지표 변수:

변수설명
fromTime데이터 조회 시작 시간 (예약어)
toTime데이터 조회 종료 시간 (예약어)
targetIds범례 위젯 사용 시 필수 추가 (예약어)

샘플 쿼리:

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

4-2. Current 타입​

적용 가능한 차트 타입: 누적 바(Stacked Bar), 스코어보드(Scoreboard)

Select 필드 필수 포함 항목:

필드명설명
value대상별 값 (필수)
target_id대상 id (필수)

지표 변수:

변수설명
fromTime / toTime동적 조회 범위 적용 시 사용 (예약어일 필요 없음)
targetIds범례 위젯 사용 시 필수 추가 (예약어)

샘플 쿼리:

SELECT target_id, max(value) 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

4-3. Scatter 타입​

적용 가능한 차트 타입: 스캐터(Scatter) — 최대 10분 범위의 데이터만 표현 가능

Select 필드 필수 포함 항목:

필드명설명
time위젯 x축에 대응되는 시간값 (필수)
elapse_time위젯 y축에 대응되는 수행시간 값 (필수)
count동일한 x축, y축 값을 가지는 수집 데이터 개수 (필수)
target_ids대상 id 리스트 (array 데이터 필드) (필수)

지표 변수:

변수설명
targetIds범례 위젯 사용 시 필수 추가 (예약어)

샘플 쿼리:

SELECT
    toStartOfMinute(collect_time) as time,
    elapsed_time,
    count(*) as count,
    groupArray(instance_id) as target_ids
FROM oracle_sql_elapse_dist
WHERE collect_time >= fromTime
AND collect_time < toTime
AND instance_id in ($_get_targets_from_tags('database', targetIds))
GROUP BY time, elapsed_time

4-4. Table 타입​

적용 가능한 차트 타입: 이퀄라이저, 트리 그리드, 상위 리스트, 파이(그래프 타입만), 필터(셀렉트2 필터 유형)

Select 필드 주의사항:

상황필수 필드
필터 위젯 셀렉트2 유형에서 사용 시name (대상 이름), value (대상 ID)
범례 위젯 대상 필터 연동 시target_id (대상 id)

지표 변수:

변수설명
clickedTime타임시리즈 차트에서 특정 시간 클릭 시 해당 시간 참조 (트리그리드용)
targetIds범례 위젯 사용 시 필수 / 알람 Table 유형 지표 사용 시 필수
fromTime알람 설정 시 조회 시작 시간 (알람 사용 시 예약어)
toTime알람 설정 시 조회 종료 시간 (알람 사용 시 예약어)

알람 설정 시: 범례 위젯 사용 여부와 관계없이 targetIds 필수, 알람 조회 시간 범위 적용 시 fromTime, toTime 필수 사용

필터 위젯 셀렉트2용 샘플 쿼리:

select
  distinct
  target_id as value,
  system_attributes['name'] as name
from target
where target_id in ($_get_targets_from_tags('database','database;tag;*'))

5. 부가 기능​

5-1. 대시보드 위젯 연계​

메뉴 경로: Dashboard > Edit > 위젯 설정 > 쿼리 정의 지표 사용

Query Manager에서 저장한 지표(Share Query 활성화 필요)를 대시보드 위젯 데이터로 활용합니다.

쿼리 매니저로 사용할 수 없는 위젯:

그래프 위젯(일부):

아키텍처 위젯:

비즈니스 위젯:

5-2. 알람(Alert) 지표 등록​

메뉴 경로: Performance Analysis > Query Manager → Setting > Alert > User Alert

지원 버전:

모듈버전
exemone-frontv3.0.508.32 이상
exemone-apiv3.0.508 이상
exemone-alerterv3.0.508.11 이상

지원 범위: Clickhouse Repository 데이터만 알람 등록 가능 (PostgreSQL 불가)

Query Manager 알람 지표 등록 절차:

단계설명
Step 1Clickhouse Repository 데이터로 지표 생성
Step 2Select 데이터 조회 칼럼에 target_id 포함 (필수)
Step 3참조 변수 적용: fromTime, toTime, targetIds (필수)
Step 4targetIds 참조변수 사용 시 태그 사용 필수
Step 5지표 저장 시 Share Query 활성화 → Data Type = Table 1개만 지정 → Alert Data 활성화

알람 등록:

단계설명
Step 1Setting > Alert > User Alert에서 알람 지표 선택 시 Query Manager에서 생성한 지표 선택
Step 2Table 유형 알람 등록 절차에 따라 진행

5-3. Notification Parameter 설정​

메뉴 경로: Setting > Alert > Notification > Add/Edit Notification

Query Manager에서 등록한 지표를 알람 Notification 발생 시 파라미터로 활용합니다.

지원 알림 유형: 이메일, 슬랙, 텔레그램, 웹훅, 온사이트 (KakaoTalk, SMS 미지원)

지원 버전:

모듈버전
exemone-db-agentv3.0.508.14
exemone-cloud-agentv3.0.508.1
exemone-receiverv3.0.508.4
exemone-ingesterv3.0.508.11
exemone-alerterv3.0.508.18
exemone-corev3.0.508.17
exemone-apiv3.0.508.51
exemone-gatewayv3.0.508.2
exemone-frontv3.0.508.39

사용 방법:

항목설명
데이터 전송 방식조회 결과 첫 번째 칼럼의 첫 번째 Row가 파라미터 데이터로 전송됩니다.
파라미터 입력 형식$qm$qm_{data_id}$ (data_id 앞에 qm_ 접두사 필수)
적용 영역fixed_contents 영역에서만 파라미터 사용 가능

6. 환경 설정 (PostgreSQL 지원)​

전제 조건: exemone-api v3.0.508.27 이상부터 지원

Query Manager에서 Clickhouse 외 PostgreSQL도 조회 가능하도록 exemone-api 설정이 필요합니다.

6-1. 바이너리 설치 환경​

파일 위치: {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

설정 후 exemone-api 재구동:

{EXEM_HOME}/onctl restart exemone-api

6-2. 도커 설치 환경​

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

spring:
...
  query-manager:
    # ClickHouse 설정
    clickhouse:
      url: jdbc:clickhouse://clickhouse:8123/default?max_execution_time=60
      username: exemone
      password: B5ICGPmyoO16xR4SzJJnYLYb7oMm1Gvd3s4I5ugY/R0=
      max-timeout: 60000
      max-connection-pool: 15

    # PostgreSQL 설정
    postgresql:
      url: jdbc:postgresql://postgresql:5432/postgres
      username: postgres
      password: B5ICGPmyoO16xR4SzJJnYLYb7oMm1Gvd3s4I5ugY/R0=
      max-timeout: 60000
      max-connection-pool: 15
      schema: public

설정 후 exemone-api 재구동:

{EXEM_HOME}/scripts restart api

주의: 바이너리와 도커 환경의 IP 주소 설정이 상이합니다. 바이너리는 127.0.0.1, 도커는 컨테이너 서비스명(예: clickhouse, postgresql)을 사용합니다.

7. 주의사항 / 참고​

항목내용
metrics/current 타입 필수 aliasmetrics, current 유형은 쿼리 결과 alias에 time, value가 필수입니다.
알람 등록 지원 범위Clickhouse Repository 데이터만 알람 등록 가능. PostgreSQL 조회 데이터는 알람 설정 불가
Alert Data 토글 활성화 조건Data Type에서 Table 1개만 지정한 경우에만 Alert Data 토글이 활성화됩니다.
targetIds 변수 사용 시태그 사용이 필수입니다. targetId를 직접 바인딩해서는 안 됩니다.
에러 발생 시 저장 불가쿼리 실행 결과에 에러가 발생한 경우 저장이 불가능합니다. 먼저 오류를 수정 후 저장하십시오.
쿼리 매니저 미지원 위젯Gauge, Action View, Heat map, Daily Comparison, Architecture 위젯, Business 위젯은 쿼리 매니저로 사용 불가합니다.
Notification 파라미터 적용 영역fixed_contents 영역에서만 파라미터 사용 가능합니다.
PostgreSQL 알람 불가PostgreSQL에서 조회한 데이터는 Alert 설정이 불가합니다.
yaml 파일 작성 시들여쓰기 및 띄어쓰기(하위 항목: 2칸)에 주의가 필요합니다.
api v3.0.508.27 미만 환경기존 spring.query-manager-datasource 항목 삭제 후 신규 설정 적용이 필요합니다.

참고 문서: