Elasticsearch 쿼리 편집기

Elasticsearch 쿼리 편집기 (Query editor)

Grafana는 Elasticsearch용 쿼리 편집기를 제공해요. Elasticsearch 쿼리는 Lucene 형식이에요. 쿼리 문법에 대한 자세한 내용은 Lucene query syntax와 Query string syntax를 참고하세요.

출처: Elasticsearch query editor

본문

참고: Lucene 쿼리를 작성할 때는 대문자 불리언 연산자 AND, OR, NOT를 사용해야 해요. 이 연산자의 소문자 버전은 Lucene 쿼리 문법에서 지원되지 않아요.

모든 쿼리 편집기에 공통된 옵션과 함수를 포함한 Grafana의 데이터 소스 질의 일반 문서는 Query and transform data를 참고하세요.

집계 유형

Elasticsearch는 집계를 세 가지 범주로 그룹화해요.

  • Bucket - 버킷 집계는 지표를 계산하지 않고 필드 값, 범위, 다양한 다른 기준에 따라 문서의 버킷을 만들어요. 자세한 내용은 Bucket aggregations 참고. 쿼리 빌더에서 메트릭 쿼리를 만들 때 Group by 아래에서 버킷 집계를 사용해요.
  • Metrics - 메트릭 집계는 sum, average, min 등과 같은 계산을 수행해요. 단일 값 또는 다중 값일 수 있어요. 자세한 내용은 Metrics aggregations 참고. 쿼리 빌더의 메트릭 쿼리 유형에서 메트릭 집계를 사용해요.
  • Pipeline - 파이프라인 집계는 문서나 필드가 아닌 다른 집계의 출력에 대해 작동해요. 자세한 내용은 Pipeline aggregations 참고.

쿼리 유형 선택

Elasticsearch 쿼리 빌더로 만들 수 있는 쿼리는 두 가지 유형이 있어요.

Preserve query 토글을 사용해 Metrics, Logs, Raw Data, Raw Document 사이를 전환할 때 Lucene 쿼리를 유지해요. 토글이 꺼져 있으면(새 쿼리의 기본값) 쿼리 유형을 전환할 때 Lucene 쿼리가 지워져요. Grafana는 새 쿼리에 대해 마지막 Preserve query 선택을 브라우저에 기억해요.

메트릭 쿼리 유형

메트릭 쿼리는 데이터를 집계하고 count, min, max 등과 같은 계산을 생성해요. 메트릭 상자를 클릭해 드롭다운 메뉴에서 옵션을 봐요. 기본값은 count예요.

Elasticsearch 쿼리 편집기를 사용할 때 여러 지표를 선택하고 여러 용어나 필터로 그룹화할 수 있어요. 오른쪽의 + 기호를 사용해 쿼리에 지표를 여러 개 추가해요. Metric 옆의 눈 아이콘을 클릭해 지표를 숨기고, 휴지통 아이콘을 클릭해 지표를 제거해요.

각 group by 옵션은 쿼리를 더 좁히는 다른 옵션 하위 집합을 가져요.

date histogram 버킷 집계 옵션에 특화된 옵션은 다음과 같아요.

  • Time field - 시간 기반 쿼리에 사용되는 필드. 기본값은 Elasticsearch details의 Time field name 설정에서 데이터 소스 구성 시 설정할 수 있어요. 기본값은 @timestamp.
  • Interval - 데이터 그룹화를 위한 시간 간격. 드롭다운에서 선택하거나 30d(30일) 같은 커스텀 간격을 입력해요. 기본값은 Auto.
  • Min doc count - 버킷에 포함하는 데 필요한 최소 문서 수. 기본값은 0.
  • Trim edges - 시간 범위의 가장자리에 있는 부분 버킷을 제거해요. 기본값은 0.
  • Offset - 각 버킷의 시작을 지정된 기간만큼 이동시켜요. 양수(+) 또는 음수(-) 값을 사용해요. 예: 1h, 5s, 1d
  • Timezone - 날짜 계산용 시간대. 기본값은 Coordinated Universal Time.

terms 버킷 집계 옵션에 대해 다음을 구성해요.

  • Order - 데이터 순서 설정. 옵션은 top 또는 bottom.
  • Size - 문서 수 또는 데이터셋 크기를 제한해요. 커스텀 숫자 또는 no limit을 설정할 수 있어요.
  • Min doc count - 쿼리에 포함할 최소 데이터 양. 기본값은 0.
  • Order by - term value, doc count 또는 count로 용어를 정렬해요.
  • Missing - 값이 없는 문서를 어떻게 처리할지 정의해요. 누락 값은 기본적으로 무시되지만 값이 있는 것처럼 처리할 수도 있어요. 자세한 내용은 Elasticsearch 문서의 Missing value 참고.

filters 버킷 집계 옵션에 대해 다음을 구성해요.

  • Query - 문서(데이터) 버킷을 만들 쿼리를 지정해요. 예는 hostname:"hostname1", product:"widget5". * 와일드카드를 사용해 임의의 문자 수와 매칭해요.
  • Label - 버킷에 라벨 또는 이름을 추가해요.

geo hash grid 버킷 집계 옵션에 대해 다음을 구성해요.

  • Precision - geo hash의 문자 수를 지정해요.

histogram 버킷 집계 옵션에 대해 다음을 구성해요.

  • Interval - 값을 버킷으로 그룹화하는 숫자 간격.
  • Min doc count - 버킷에 포함하는 데 필요한 최소 문서 수. 기본값은 0.

nested group by 옵션은 현재 실험적이며, 필드를 선택한 다음 그 필드에 특화된 설정을 선택할 수 있어요.

+ 기호를 클릭해 여러 group by 옵션을 추가해요. 데이터는 순서대로 그룹화돼요(먼저 by, 그다음 by).

로그 쿼리 유형

로그 쿼리는 Elasticsearch 로그 데이터를 분석해요. 다음 옵션을 구성할 수 있어요.

  • Logs Options/Limit - 분석할 로그 수를 제한해요. 기본값은 500.

쿼리 옵션

쿼리 편집기에서 Options 섹션을 열어 쿼리 수준 설정을 구성해요.

  • Limit 또는 Size - Logs 및 Raw Data 쿼리에서 반환할 최대 문서 수를 설정해요. 기본값은 500.
  • Include runtime fields - 활성화하면 인덱스 매핑에 정의된 런타임 필드가 응답에 포함돼요. 이 옵션은 Builder 모드에서 사용할 수 있어요.

Raw 쿼리 편집기

Raw 쿼리 편집기는 네이티브 Elasticsearch Query DSL로 Elasticsearch 쿼리를 작성할 수 있게 해줘요.

Builder와 Code 모드 전환

Raw 쿼리 편집기에 접근하려면 쿼리 편집기 오른쪽 위의 Code 토글을 클릭해요. Builder와 Code 모드 사이를 전환할 수 있어요.

  • Builder - 드롭다운 메뉴와 폼이 있는 시각적 쿼리 빌더
  • Code - 원시 Elasticsearch DSL 쿼리를 작성하는 JSON 편집기

Raw DSL 쿼리 작성

Code 모드에서 JSON 형식으로 완전한 Elasticsearch 쿼리 DSL을 작성할 수 있어요. 편집기는 다음을 제공해요.

  • JSON용 문법 강조
  • 자동 서식 - Format 버튼을 클릭하거나 Shift+Alt+F를 눌러 쿼리 서식 지정
  • 키보드 단축키 - Ctrl+Enter(Mac에서는 Cmd+Enter)를 눌러 쿼리 실행
  • 실시간 검증 - 잘못된 JSON은 오류 메시지와 함께 강조 표시

시간 범위 처리

대시보드에서 시간 범위로 필터링하려면 Raw DSL에서 $__from 및 $__to 매크로를 사용해야 해요.

@timestamp 필드를 사용해 대시보드 시간 범위를 적용하는 예시 쿼리:

{
  "query": {
    "bool": {
      "must": [
        {
          "range": {
            "@timestamp": {
              "gte": "$__from",
              "lte": "$__to",
              "format": "epoch_millis"
            }
          }
        }
      ]
    }
  }
}

지원되는 쿼리 유형

Raw 쿼리 편집기는 모든 쿼리 유형을 지원해요.

  • Metrics 쿼리는 집계로 시계열 데이터를 질의하는 데 사용해요. 쿼리 파서가 DSL에서 버킷 및 지표 집계를 자동으로 추출해 응답 처리에 사용해요.
  • Logs 쿼리는 로그 데이터를 질의하는 데 사용해요.

ES|QL 쿼리 편집기

ES|QL 쿼리 편집기는 파이프 기반 쿼리 언어인 ES|QL(Elasticsearch Query Language)로 Elasticsearch를 질의할 수 있게 해줘요. 빌더 UI의 집계 구성에 의존하는 Lucene 쿼리와 달리 ES|QL은 단일 쿼리 문자열로 필터링, 집계, 변환을 표현할 수 있어요.

ES|QL 문법과 개념 소개는 Elasticsearch 문서의 Get started with ES|QL queries를 참고하세요.

ES|QL 쿼리에 시간 필터가 없으면 Grafana가 대시보드 또는 Explore 시간 선택기를 기반으로 시간 범위 필터를 자동 추가해요.

인덱스 선택

편집기가 인덱스 선택을 처리하는 방식은 데이터 소스 구성에 따라 달라요.

  • 인덱스 이름이 구성되지 않음: ES|QL 쿼리에서 직접 FROM 명령으로 질의할 인덱스를 지정해요. 각 인덱스에 대해 별도의 데이터 소스를 만들지 않고도 어떤 인덱스든 질의할 수 있어요.
  • 인덱스 이름이 구성됨: ES|QL 필드가 포커스를 받으면 편집기가 자동으로 FROM $__index를 삽입해요. 필요하면 이를 재정의하고 다른 인덱스를 질의할 수 있어요.

편집기 기능

ES|QL 코드 편집기는 다음을 제공해요.

  • 코드 제안 - ES|QL 명령과 함수 자동 완성
  • 오류 강조 - 편집기에서 문법 오류를 강조하고 Elasticsearch의 오류 메시지를 직접 표시
  • 문법 강조 - 가독성을 위해 ES|QL 키워드, 연산자, 값을 색상으로 구분

예시 쿼리

다음 예시는 일반적인 ES|QL 쿼리 패턴을 보여줘요.

기본 집계

필드로 그룹화된 문서 수 계산:

FROM logs-*
| STATS count = COUNT(*) BY host.name
| SORT count DESC
| LIMIT 10
시간에 따른 필터와 집계

필드 값으로 필터링하고 시간 간격에 대한 평균 계산:

FROM metrics-*
| WHERE service.name == "api-gateway"
| STATS avg_duration = AVG(transaction.duration.us) BY @timestamp = BUCKET(@timestamp, 1 minute)
| SORT @timestamp
로그 메시지 검색

로그 데이터에서 특정 패턴 검색:

FROM logs-*
| WHERE message LIKE "*error*" AND log.level == "ERROR"
| KEEP @timestamp, message, host.name, log.level
| SORT @timestamp DESC
| LIMIT 100
PromQL 지표 쿼리

Metrics 쿼리 유형을 선택하면 ES|QL도 PROMQL 소스 명령을 받아들여요. Grafana는 ES|QL STATS 쿼리와 같은 방식으로 응답을 시계열 프레임으로 처리해요. PROMQL은 쿼리의 첫 번째 명령이어야 해요(앞에 주석은 허용).

PROMQL index=metrics-* step=1m avg(metrics.system.cpu.logical.count)

ES|QL에 대해 더 배우기

ES|QL 문법, 명령, 함수에 대한 자세한 내용은 다음 Elasticsearch 문서를 참고하세요.

템플릿 변수 사용

템플릿 변수로 쿼리를 확장할 수도 있어요. terms 쿼리는 기본적으로 500개 결과 제한이 있어요. 커스텀 한도를 설정하려면 쿼리에 size 속성을 설정하세요.

더 알아보기 (Learn more)