OpenTSDB 쿼리 편집기
OpenTSDB 쿼리 편집기 (OpenTSDB query editor)
쿼리 편집기로 OpenTSDB 쿼리를 시각적으로 구성할 수 있어요. 사용 가능한 옵션은 데이터 소스에 구성한 OpenTSDB 버전에 따라 달라집니다. 메트릭, 다운샘플, 필터, 태그, rate 계산, 집계자, fill 정책, 자동완성 등 전체 쿼리 구성을 다룹니다.
출처: 문서
본문
쿼리 편집기로 OpenTSDB 쿼리를 시각적으로 만들 수 있어요. 사용 가능한 옵션은 데이터 소스에 구성한 OpenTSDB 버전에 따라 달라집니다.
쿼리 편집기 접근: OpenTSDB 쿼리 편집기는 Explore 페이지에 있으며, 대시보드 패널에서 패널 오른쪽 위 줄임표 → Edit 으로도 접근할 수 있어요. 쿼리를 만들려면 패널에서 OpenTSDB 데이터 소스를 선택하고 아래 섹션으로 쿼리를 구성합니다.
메트릭 섹션 (Metric section)
| 필드 | 설명 |
|---|---|
| Metric | 쿼리할 메트릭 이름. 입력 시 OpenTSDB 서버의 자동완성 제안 표시 |
| Aggregator | 여러 시계열을 결합하는 집계 함수. 기본값 sum |
| Alias | 시리즈의 커스텀 표시 이름. $tag_<tagname> 으로 별칭에 태그 값 포함 |
별칭 패턴(Alias patterns): 별칭 필드는 태그 값을 사용한 동적 치환을 지원합니다. $tag_<tagname> 패턴을 사용하며 <tagname>은 메트릭의 태그 이름이에요.
| 패턴 | 설명 | 예시 출력 |
|---|---|---|
$tag_host |
host 태그 값 삽입 |
webserver01 |
$tag_env |
env 태그 값 삽입 |
production |
$tag_host - CPU |
태그 값과 정적 텍스트 결합 | webserver01 - CPU |
$tag_host ($tag_env) |
여러 태그 치환 | webserver01 (production) |
다운샘플 섹션 (Downsample section)
다운샘플링은 시간 간격에 걸쳐 값을 집계해 반환되는 데이터 포인트 수를 줄여요. 이는 쿼리 성능을 개선하고 전송 데이터량을 줄입니다.
| 필드 | 설명 |
|---|---|
| Down sample | 다운샘플링 시간 간격. Down sample 라벨 옆 입력에 값 입력하거나, 비워 두면 패널 시간 범위·너비 기반 자동 간격 사용 |
| Aggregator | 다운샘플링 집계 함수. 기본값 avg |
| Fill | (버전 2.2+) 누락 데이터 포인트에 대한 fill 정책. 기본값 none |
| Disable downsampling | 다운샘플링을 완전히 비활성화하는 토글. 원시 데이터 포인트가 필요할 때 사용 |
간격 형식(Interval format):
| 형식 | 설명 | 예시 |
|---|---|---|
s |
초 | 30s |
m |
분 | 5m |
h |
시 | 1h |
d |
일 | 1d |
w |
주 | 1w |
간격을 비워 두면 Grafana가 패널 시간 범위와 픽셀 너비에 따라 적절한 간격을 자동 계산합니다.
필터 섹션 (Filters section)
필터(OpenTSDB 2.2+에서 사용 가능)는 레거시 태그 기반 필터링을 대체하는 고급 필터링을 제공합니다.
| 필드 | 설명 |
|---|---|
| Key | 필터링할 태그 키. 자동완성 제안에서 선택하거나 커스텀 값 입력 |
| Type | 필터 유형. 필터 값이 어떻게 매칭되는지 결정. 기본값 iliteral_or |
| Filter | 필터 값 또는 패턴. 태그 값 자동완성 지원 |
| Group by | 이 태그 키로 결과를 그룹핑하는 토글. 활성화 시 각 고유 값에 대해 별도 시계열 반환 |
필터 추가·편집·제거: "Filters" 옆 + 버튼으로 새 필터 추가, 필터 필드 구성 후 add filter 클릭. 기존 필터는 연필 아이콘으로 편집, x 아이콘으로 제거. 단일 쿼리에 여러 필터를 추가할 수 있으며 모든 필터는 AND 로직으로 결합됩니다.
필터 유형 (Filter types):
| 유형 | 설명 | 예시 |
|---|---|---|
literal_or |
정확한 값 매칭. ` | `로 여러 값 지정 |
iliteral_or |
대소문자 무시 리터럴 매칭 | WEB01|web02 |
wildcard |
* 와일드카드 매칭 |
web-*-prod |
iwildcard |
대소문자 무시 와일드카드 | WEB-* |
regexp |
정규식 매칭 | web-[0-9]+ |
not_literal_or |
정확한 값 제외 | web01|web02 |
not_iliteral_or |
대소문자 무시 제외 | TEST|DEV |
Group by 동작: 필터에 대해 Group by 가 활성화되면 결과가 필터링된 태그의 각 고유 값에 대한 별도 시계열로 분할되고, 각 시계열은 태그 값으로 라벨링됩니다. 호스트·환경·다른 차원 간 값 비교에 유용해요. 비활성화되면 모든 매칭 시계열이 선택한 집계자로 결합되어 단일 집계 시계열이 반환됩니다.
태그 섹션 (Tags section)
태그는 key-value 쌍으로 메트릭을 필터링합니다. OpenTSDB 2.2 이전 버전의 레거시 필터링 방법이에요.
| 필드 | 설명 |
|---|---|
| Key | 필터링할 태그 키. 자동완성 제안에서 선택 |
| Value | 매칭할 태그 값. 이 키의 모든 값을 매칭하려면 * 사용 |
태그 추가·편집·제거: "Tags" 옆 + 버튼으로 추가(태그 키 선택/입력, 태그 값 선택/입력, * 와일드카드, add tag 적용). 연필로 편집, x로 제거.
참고: 태그는 OpenTSDB 2.2 이상에서 더 이상 사용되지 않아요(deprecated). 와일드카드·정규식·제외 패턴을 포함한 더 강력한 필터링 옵션을 위해 Filters 를 사용하세요.
주의: 태그와 필터는 상호 배타적이에요. 필터가 정의되어 있으면 태그를 추가할 수 없고 그 반대도 마찬가지입니다. 둘 다 사용하려 하면 쿼리 편집기가 경고를 표시합니다.
Rate 섹션 (Rate section)
Rate 섹션은 지속적으로 증가하는 카운터 메트릭에 필수인 변화율(rate)을 계산합니다.
| 필드 | 설명 |
|---|---|
| Rate | rate 계산 활성화 토글. 연속 값 사이의 초당 변화율 계산 |
| Counter | (Rate 활성화 시) 지속적으로 증가하며 리셋될 수 있는 카운터임을 나타내는 토글 |
| Counter max | (Counter 활성화 시) 카운터가 래핑되기 전의 최대 값 |
| Reset value | (Counter 활성화 시) 래핑 후 카운터가 리셋되는 값. 기본값 0 |
| Explicit tags | (버전 2.3+) 지정된 모든 태그가 매칭 시계열에 존재하도록 요구하는 토글 |
rate 계산 사용 시점: 네트워크 바이트 송수신, 요청 수, 오류 수, 디스크 I/O 작업 같은 지속적으로 증가하는 카운터 메트릭에서 Rate 를 활성화하세요. Counter 는 서비스 재시작 후 0으로 리셋될 수 있는 메트릭에서 활성화합니다. Counter max: 64비트 카운터는 18446744073709551615, 32비트 카운터는 4294967295. Explicit tags 활성화 시(2.3+) OpenTSDB는 쿼리에 지정된 모든 태그가 있는 시계열만 반환해, 일부 시계열에 태그가 누락될 때 예상치 못한 결과를 방지합니다.
집계자 (Aggregators)
집계 함수는 여러 시계열을 하나로 결합합니다. 데이터 소스는 내장 기본 목록(avg, sum, min, max, dev, zimsum, mimmin, mimmax)을 포함한 뒤 OpenTSDB 서버에서 가져온 목록으로 교체합니다. 결과적으로 count 같은 추가 집계자를 볼 수 있어요. 사용 가능한 집계자는 OpenTSDB 서버 버전·구성에 따라 달라지며, 드롭다운은 /api/aggregators 엔드포인트에서 동적으로 채워집니다.
일반 집계자:
| 집계자 | 설명 | 사용 사례 |
|---|---|---|
sum |
각 타임스탬프의 모든 값 합산 | 모든 서버의 총 요청 |
avg |
각 타임스탬프의 값 평균 | 호스트 간 평균 CPU 사용량 |
min |
각 타임스탬프의 최소값 | 가장 낮은 응답 시간 |
max |
각 타임스탬프의 최대값 | 최고 메모리 사용량 |
dev |
표준편차 계산 | 응답 시간 변동성 측정 |
count |
데이터 포인트 수 계산 | 보고하는 호스트 수 |
보간 집계자(Interpolation aggregators):
| 집계자 | 설명 |
|---|---|
zimsum |
누락 데이터를 0으로 처리해 값 합산 |
mimmin |
누락(보간된) 데이터 무시하고 최소값 |
mimmax |
누락(보간된) 데이터 무시하고 최대값 |
Fill 정책 (Fill policies)
Fill 정책(OpenTSDB 2.2+에서 사용 가능)은 다운샘플링 중 누락 데이터 포인트를 처리하는 방법을 결정합니다. 데이터에 간격이 있거나 불규칙한 수집 간격이 있을 때 중요해요.
| 정책 | 설명 | 사용 사례 |
|---|---|---|
none |
누락 값을 채우지 않음. 간격이 데이터에 남음 | 기본 동작, 데이터 충실도 보존 |
nan |
누락 값을 NaN(Not a Number)으로 채움 | 누락 데이터를 전파해야 하는 계산에 유용 |
null |
누락 값을 null로 채움 | 시각화는 null 지점에서 간격 표시 |
zero |
누락 값을 0으로 채움 | 누락 데이터를 0으로 처리, 카운터에 유용 |
자동완성 제안 (Autocomplete suggestions)
| 필드 | 소스 | 설명 |
|---|---|---|
| Metric | /api/suggest?type=metrics |
입력 시 메트릭 이름 제안 |
| Tag keys | 이전 쿼리 결과 | 선택한 메트릭 기반 태그 키 제안 |
| Tag values | /api/suggest?type=tagv |
입력 시 태그 값 제안 |
| Filter keys | 이전 쿼리 결과 | 필터 구성을 위한 태그 키 제안 |
자동완성 요구사항: OpenTSDB suggest API가 서버에서 활성화되어야 하고, OpenTSDB 데이터베이스에 메트릭이 존재해야 해요. 데이터 소스 구성의 Lookup limit 설정이 반환되는 제안의 최대 수를 제어합니다. 작동하지 않으면 Troubleshooting을 참고하세요.
템플릿 변수 사용 (Use template variables)
쿼리 편집기의 모든 텍스트 필드에서 템플릿 변수를 사용할 수 있어요. 템플릿 변수는 쿼리 실행 시 현재 값으로 대체됩니다. 일반적인 용도: Metric 필드 $metric(동적 메트릭 선택), Filter values $host(변수 선택 호스트로 필터링), Tag values $environment(환경으로 필터링). 자세한 내용은 Template variables 참고.
쿼리 예시 (Query examples)
기본 메트릭 쿼리 + 태그 필터링: Metric sys.cpu.user, Aggregator avg, Tags host=webserver01 → webserver01 호스트의 평균 CPU 사용량 반환.
와일드카드 필터 쿼리(2.2+): Metric http.requests.count, Aggregator sum, Filter Key host, Filter Type wildcard, Filter Value web-*, Group by enabled → web-* 매칭 모든 호스트의 HTTP 요청 수 합산 + 호스트별 그룹.
네트워크 카운터 rate 계산: Metric net.bytes.received, Aggregator sum, Rate/Counter enabled, Counter max 18446744073709551615 → 초당 수신 바이트 rate. 카운터 랩 처리를 위해 64비트 부호 없는 정수 최대값 설정.
별칭 패턴 사용: Metric app.response.time, Aggregator avg, Tags host=*, env=production, Alias $tag_host - Response Time → webserver01 - Response Time 같은 읽기 쉬운 범례 라벨.
커스텀 간격 다운샘플: Metric sys.disk.io.bytes, Aggregator sum, Downsample Interval 5m, Downsample Aggregator avg, Fill zero → 디스크 I/O 데이터를 5분 평균으로 줄이고 간격을 0으로 채움.
필터로 환경 비교: Metric app.errors.count, Aggregator sum, Filter Key env, Type literal_or, Value staging|production, Group by enabled → 스테이징·프로덕션 오류 수를 비교용 별도 시계열로.
특정 호스트 제외: Metric sys.cpu.user, Aggregator avg, Filter Key host, Type not_literal_or, Value test-server|dev-server, Group by enabled → test-server·dev-server 제외한 모든 호스트의 CPU.
명시적 태그 쿼리(2.3+): Metric app.request.latency, Aggregator avg, Filter Key host, Type wildcard, Value *, Group by enabled, Explicit tags enabled → host 태그가 정의된 시계열만 반환.