콘솔 템플릿

콘솔 템플릿 (Console templates)

프로메테우스의 콘솔 템플릿(console templates)을 사용해 나만의 모니터링 콘솔 페이지를 만드는 방법을 설명하는 문서예요. 표현식 브라우저나 Grafana 같은 시각화 도구가 아니라, 프로메테우스 서버가 제공하는 Go 템플릿 기반의 사용자 정의 웹 페이지를 만들 수 있는 기능이에요.

팀 내부에서 특정 서비스나 하드웨어의 상태를 한눈에 보여주는 전용 페이지를 만들고 싶을 때 유용해요. 템플릿 언어의 기본 문법, 콘솔 빌드 방법, 링크 추가, 그리고 이전 프로메테우스 2.0 이전 버전 콘솔에서의 마이그레이션까지 다룹니다.

출처: 문서

본문

프로메테우스는 자체 템플릿 시스템을 제공하며, 이를 통해 PromQL 쿼리를 기반으로 한 나만의 콘솔(대시보드) 페이지를 만들 수 있어요. 콘솔은 HTML 페이지로 작성되며, 프로메테우스 서버가 이를 렌더링해서 웹 UI에 제공해요.

콘솔 템플릿의 위치

콘솔 템플릿은 프로메테우스의 -web.console.templates 및 -web.console.libraries 플래그로 지정된 디렉토리에 위치해요. 기본값은 각각 consoles/와 console_libraries/예요. 콘솔 템플릿이 들어있는 디렉토리에 HTML 파일을 추가하면 곧바로 사용할 수 있어요.

-web.console.templates에 있는 각 템플릿은 메트릭을 시각화하는 HTML 문서예요. -web.console.libraries에 있는 라이브러리는 .lib 파일로, 템플릿에서 재사용할 수 있는 공통 함수와 매크로를 정의해요.

콘솔 만들기

콘솔 템플릿은 HTML 파일이며, 그 안에서 PromQL 쿼리를 실행해 데이터를 그래프로 렌더링할 수 있어요. 기본적인 콘솔 구조는 다음과 같아요:

{{template "head" .}}

{{template "prom_right_table_head"}}
<tr>
  <th>My Metric</th>
  <td>{{template "prom_query_drilldown" (args "my_metric")}}</td>
</tr>
{{template "prom_right_table_tail"}}

{{template "prom_content_head" .}}
<h1>My Console</h1>

<p>Some description of this console.</p>

{{template "prom_query_table" (args "rate(my_metric[5m])")}}

{{template "prom_content_tail" .}}

{{template "tail" .}}
  • {{template "head" .}}와 {{template "tail" .}}는 페이지의 공통 구조(헤더·푸터)를 넣는 템플릿 사용이에요
  • prom_query_drilldown, prom_query_table 등은 console_libraries에 있는 재사용 가능한 라이브러리 템플릿으로, 쿼리 결과를 표나 그래프로 렌더링해요
  • args 함수는 여러 인자를 템플릿 함수에 전달하는 데 사용돼요
  • prom_content_head/prom_content_tail은 본문 영역을 감싸요

이렇게 작성한 콘솔 페이지는 프로메테우스 웹 UI의 콘솔 목록에서 접근할 수 있어요.

콘솔 라이브러리와 템플릿 함수

console_libraries 디렉토리의 .lib 파일에는 공통 그래프·테이블 렌더링 함수가 정의돼 있어요. 예를 들어:

  • prom_query_drilldown: 쿼리 결과를 클릭하면 상세 보기로 드릴다운하는 링크로 렌더링
  • prom_query_table: 쿼리 결과를 표로 렌더링
  • prom_graph: 시계열 그래프를 렌더링

이 함수들은 프로메테우스 서버가 제공하는 템플릿 함수(query, args, prom_query_drilldown 등)와 함께 쓰여요. 자세한 템플릿 함수 목록은 문서의 "Learning more about the template functions" 섹션을 참고할 수 있어요.

PromQL query 함수 예시:

{{query "rate(my_metric[5m])"}}

query 함수는 서버에서 PromQL을 실행한 뒤 결과를 템플릿에 제공해요.

링크 추가하기

콘솔 페이지에서는 프로메테우스 표현식 브라우저나 다른 서비스로 연결되는 링크를 추가할 수 있어요. 예를 들어 콘솔에서 특정 표현식 브라우저로 바로 이동하는 링크:

<a href="{{ pathPrefix }}/graph?g0.expr={{ . | query | first | label "job" }}">Open in Grafana/Graph</a>

pathPrefix는 프로메테우스가 리버스 프록시 뒤에 배치된 경우에도 올바른 경로를 만들도록 도와주는 내장 변수예요.

2.0 이전 버전 콘솔에서 마이그레이션

프로메테우스 2.0에서 Grafana가 프로메테우스 공식 시각화 도구가 되면서, 기존 콘솔 템플릿은 더 이상 기본으로 제공되지 않게 됐어요. 2.0 이전 프로메테우스 배포판에 포함돼 있던 콘솔 템플릿(예: node exporter 콘솔)을 여전히 사용하고 있다면, 필요에 맞게 직접 관리하거나 가져와서 -web.console.templates에 넣어 사용할 수 있어요. 다만 프로메테우스는 기본적으로 콘솔 템플릿을 더 이상 번들로 제공하지 않으므로, 직접 배치·유지보수해야 해요.

더 알아보기 (Learn more)