Explore의 쿼리 편집기

Explore의 쿼리 편집기 (Query editor in Explore)

쿼리 편집기는 데이터 소스에 대한 쿼리를 구성하는 인터페이스예요. 각 데이터 소스의 쿼리 편집기는 고유한 기능을 활용하는 쿼리를 작성하는 데 도움을 주는 맞춤형 사용자 인터페이스를 제공해요. 쿼리 언어 간의 차이 때문에 각 데이터 소스 쿼리 편집기는 모양과 기능이 달라요.

출처: Query editor in Explore

본문

데이터 소스에 따라 쿼리 편집기는 자동 완성 기능, 지표 이름, 변수 제안, 또는 시각적 쿼리 구축 인터페이스를 제공할 수 있어요.

특정 데이터 소스의 고유한 쿼리 편집기 기능에 대한 자세한 내용은 해당 문서를 참고하세요.

  • Grafana에 포함된 데이터 소스는 Built-in core data sources를 참고하세요. 각 코어 데이터 소스 문서로 연결돼요.
  • 플러그인으로 설치된 데이터 소스는 해당 플러그인의 문서를 참고하세요.
    • Grafana 플러그인 카탈로그의 데이터 소스 플러그인은 카탈로그 목록에 문서를 연결하거나 포함해요. 플러그인 카탈로그에 대한 자세한 내용은 Plugin management를 참고하세요.
    • Grafana Enterprise 데이터 소스 플러그인 문서 링크는 Enterprise plugins index를 참고하세요.

쿼리 문법

각 데이터 소스는 데이터를 요청하기 위해 서로 다른 쿼리 언어를 사용해요. 특정 데이터 소스의 고유 쿼리 언어에 대한 자세한 내용은 해당 문서를 참고하세요.

PostgreSQL 예시:

SELECT hostname FROM host WHERE region IN($region)

PromQL 예시:

query_result(max_over_time(<metric>[${__range_s}s]) != <state>)

특수 데이터 소스

Grafana는 Grafana, Mixed, Dashboard라는 세 가지 특수 데이터 소스도 포함해요. 자세한 내용은 Data sources를 참고하세요.

저장된 쿼리 (Saved queries)

참고: Saved queries는 Grafana Enterprise와 Grafana Cloud에서만 사용할 수 있어요.

만든 쿼리를 저장해 조직의 다른 사용자와 재사용할 수 있어요. 이는 조직의 사용자들이 쿼리 언어를 알거나 직접 쿼리를 만들지 않고도 Explore에서 인사이트를 찾는 데 도움을 줘요. 또한 여러 사용자가 같은 데이터 소스에 같은 쿼리를 여러 번 만드는 것을 피할 수 있게 해줘요.

저장된 쿼리는 다음에서 지원돼요.

저장된 쿼리에 대해 더 알아보기:

  • Saved queries 대화 상자
  • 역할, 권한 및 RBAC
  • 쿼리 저장 방법
  • 저장된 쿼리의 변수
  • 코드로 저장된 쿼리 관리
  • 알려진 제한 사항

Saved queries 대화 상자

Saved queries 대화 상자는 조직의 모든 저장된 쿼리에 대한 접근을 제공해요.

저장된 쿼리에 세 가지 방법으로 접근할 수 있어요.

  • Ctrl + K 또는 Cmd + K를 눌러 명령 팔레트를 열고 "Saved queries"를 검색한 뒤 Open saved queries 작업을 선택해요. Shared queries 대화 상자가 열리며 쿼리를 선택하고 Open in Explore를 클릭할 수 있어요.
  • 쿼리 편집기에서 Saved queries > Replace query를 클릭해요.
  • 쿼리 편집기 하단에서 Add from saved queries를 클릭해요.

Add from saved queries를 클릭하면 추가 쿼리가 더해지고, Replace query를 클릭하면 구성된 쿼리가 업데이트돼요.

Saved queries 대화 상자에서 다음을 할 수 있어요.

  • 데이터 소스 이름, 쿼리 내용, 제목 또는 설명으로 쿼리 검색
  • 쿼리를 알파벳순 또는 생성 날짜순으로 정렬
  • 데이터 소스 이름, 작성자 이름, 태그로 필터. 태그 필터는 OR 연산자를 사용하고, 다른 필터는 AND 연산자를 사용해요. Remember filters 스위치로 필터 선택을 로컬 저장소에 세션 간 유지할 수 있어요.
  • 별표를 붙여 Starred queries 필터 보기에 나타나게 해요.
  • 저장된 쿼리 복제 또는 삭제
  • 쿼리 제목, 설명, 태그 편집
  • 대화 상자 하단의 Edit을 클릭해 쿼리 본문 업데이트

Starred queries 필터 보기에서도 동일한 검색, 필터, 정렬 옵션을 모두 적용할 수 있어요.

팁: Loki, Mimir, Tempo, 또는 Pyroscope 데이터 소스가 있는 쿼리를 선택하면 Saved queries 대화 상자에 Drilldown 버튼이 표시돼요. 버튼을 클릭하면 쿼리의 컨텍스트를 유지하면서 관련 Drilldown 앱을 열어요. 이러한 앱은 Drilldown 문서에서 자세히 알아보세요.

역할, 권한 및 RBAC

저장된 쿼리는 역할 기반 접근 제어를 지원해요. 기본적으로 저장된 쿼리에는 두 가지 RBAC 역할이 있어요.

  • Writer: 모든 저장된 쿼리 생성, 업데이트, 삭제
  • Reader: 저장된 쿼리 재사용

Grafana v12.4에서 RBAC 지원이 추가되기 전에 저장된 쿼리를 사용했다면 Grafana 사용자 역할이 다음과 같이 매핑돼요.

  • Admin > Writer
  • Editor > Writer
  • Viewer > Reader

쿼리 저장

만든 쿼리를 저장하려면:

  1. 쿼리 편집기에서 Saved queries 드롭다운 메뉴를 열고 Save query 옵션을 클릭해요.
  2. Saved queries 대화 상자에서 나중에 찾기 쉬운 쿼리의 제목을 입력해요.
  3. (선택) 설명과 관련 태그를 입력해요.
  4. Save를 클릭해요.

저장된 쿼리의 변수

저장된 쿼리에 변수가 포함되면 쿼리를 수정하지 않고 커스텀 값에 매핑해 변수를 대체할 수 있어요. 이는 변수 이름이나 사용 가능한 값이 대시보드마다 다른 환경에서 유용해요.

Grafana는 선택 사항을 대시보드에 삽입하기 전에 쿼리에 적용해요. 그러나 대체는 쿼리가 재사용될 때만 적용되며 원래 저장된 쿼리는 변경되지 않아요.

코드로 저장된 쿼리 관리

Grafana Terraform provider로 저장된 쿼리를 코드로 관리할 수 있어요. 이를 통해 쿼리 라이브러리를 버전 관리하고 인스턴스 간 일관성을 유지할 수 있어요. 자세한 내용은 Manage saved queries using Terraform을 참고하세요.

알려진 제한 사항

  • 쿼리를 저장할 때 검증이 수행되지 않으므로 잘못된 쿼리를 저장할 수 있어요. 저장하기 전에 쿼리가 제대로 동작하는지 확인해야 해요.
  • 최대 1000개 쿼리를 저장할 수 있어요.
  • Explore에서 여러 쿼리가 열려 있고 그중 하나를 Saved queries 대화 상자의 Edit in Explore 기능으로 편집하면, 편집한 쿼리가 Explore의 열린 쿼리를 대체해요.

쿼리 추가

쿼리를 추가하려면:

  1. 기본이 아닌 데이터 소스를 사용하려면 툴바의 데이터 소스 드롭다운 메뉴를 클릭해 선택해요.

여러 데이터 소스를 사용하려면 이 단계에서 Mixed 데이터 소스를 선택해요. 쿼리 편집기에 보조 데이터 소스 선택기가 표시돼요.

  1. 쿼리를 만들려면 다음 중 하나를 해요.
    • 데이터 소스의 쿼리 언어로 쿼리를 작성하거나 구성해요.
    • Replace를 클릭해 저장된 쿼리를 재사용해요.

참고: Saved queries는 Grafana Enterprise와 Grafana Cloud에서만 사용할 수 있어요.

  1. (선택) 재사용할 쿼리를 저장하려면 편집기 창에서 Save를 클릭해요.
  2. (선택) 필요하면 쿼리 편집기 하단에서 Add query 또는 Add from saved queries를 클릭해 쿼리를 더 추가해요.
  3. 툴바의 Run query 아이콘을 클릭해요.

Grafana가 데이터 소스를 질의해요. 데이터 소스가 그래프와 테이블 데이터를 지원하면 Explore는 결과를 Graph에 표시해요.

쿼리 관리

다음 표는 각 쿼리에 대해 수행할 수 있는 작업을 설명해요.

아이콘 설명
Replace query 아이콘 저장된 쿼리 옵션. 드롭다운 목록을 열고 Save query 또는 Replace query에서 선택(Enterprise와 Cloud 전용).
Help 아이콘 쿼리 편집기 도움말 토글. 데이터 소스가 지원하면 이 아이콘을 클릭해 쿼리 편집기 사용 방법 정보를 표시하거나 일반 쿼리에 빠른 접근을 제공. More query actions 메뉴를 클릭해 이 옵션에 접근.
Create recorded query 아이콘 기록 쿼리를 만들어 설정된 간격으로 데이터 포인트의 스냅샷을 찍어 시간에 따른 추세를 볼 수 있게 함(Enterprise와 Cloud 전용).
Duplicate 아이콘 쿼리를 복사. 중복 쿼리는 유사한 여러 복잡한 쿼리를 작업할 때 유용하며, 다른 변형을 실험하거나 사소한 수정을 하려 할 때 유용. More query actions 메뉴를 클릭해 이 옵션에 접근.
Hide 아이콘 쿼리를 숨김. Grafana는 숨겨진 쿼리를 데이터 소스로 보내지 않아요.
Remove 아이콘 쿼리를 제거. 쿼리를 제거하면 영구 삭제되지만, 이전에 저장한 패널 버전으로 되돌려 삭제된 쿼리를 복구할 수 있는 경우도 있어요.

더 알아보기 (Learn more)