템플릿 변수

원문 보기 위키 갱신 2026.10.05

템플릿 변수 (Template Variables)

템플릿 변수(Template Variables)를 사용하면 대시보드의 위젯을 동적으로 필터링하거나 그룹화할 수 있어요. 템플릿 변수 선택에서 저장된 뷰(saved views)를 만들면 드롭다운 선택을 통해 시각화를 정리하고 탐색할 수 있어요.

템플릿 변수는 태그 또는 속성(Attribute), 이름(Name), 기본값(Default Value), 사용 가능한 값(Available Values)으로 정의돼요. 태그는 권장되는 태깅 형식(<KEY>:<VALUE>)을 따른다면 <KEY>가 됩니다. 기본값은 대시보드가 로드될 때 자동으로 나타나는 값으로 기본적으로 *이에요.

출처: 문서

본문

개요

템플릿 변수를 사용하면 대시보드의 위젯을 동적으로 필터링하거나 그룹화할 수 있어요. 템플릿 변수 선택에서 저장된 뷰를 만들면 드롭다운 선택을 통해 시각화를 정리하고 탐색할 수 있어요.

템플릿 변수는 다음으로 정의돼요:

태그 또는 속성:
- 태그: 권장되는 태깅 형식(<KEY>:<VALUE>)을 따른다면 태그는 <KEY>예요.
- 속성: 파셋(facet) 또는 측정값(measure)을 템플릿 변수로 사용해요.
이름: 대시보드의 쿼리에 나타나는 템플릿 변수의 고유 이름이에요. 템플릿 변수는 선택한 태그 또는 속성 뒤에 자동으로 이름이 붙어요.
기본값: 대시보드가 로드될 때 자동으로 나타나는 태그 또는 속성 값이에요. 기본값은 *이에요.
사용 가능한 값: 드롭다운 메뉴에서 선택할 수 있는 태그 또는 속성 값이에요. 기본값은 (all)이에요. 사용 가능한 값 목록에는 항상 *이 포함되며, 이는 태그 또는 속성의 모든 값을 쿼리해요.

템플릿 변수 값

템플릿 변수 값(템플릿 변수 드롭다운 메뉴로 사용할 수 있는 값)은 대시보드의 위젯이 사용하는 소스를 기반으로 채워져요. 예를 들어 대시보드에 로그를 쿼리하는 위젯만 있다면 로그의 값만 표시돼요. 대시보드에 로그, 메트릭, RUM을 쿼리하는 위젯이 있다면 로그, 메트릭, RUM의 값이 모두 표시돼요.

대부분의 소스에서 템플릿 변수 값은 대시보드의 전체 시간 범위(global time frame)와 관련이 있어요. 예를 들어:

대시보드의 시간 범위가 지난 15분으로 설정된 경우 지난 15분 동안의 템플릿 변수 값만 표시돼요.
대시보드 시간 범위가 지난 8월 15일 자정부터 23:59까지로 설정된 경우 해당 시간 범위의 값만 표시돼요.

데이터 소스	데이터 쿼리 기간
Metrics	현재 - 48시간
Cloud cost	현재 - 48시간
기타 모든 소스	대시보드 시간 범위

참고: 찾고 있는 태그나 속성이 표시되지 않는다면 해당 데이터가 최근에 Datadog에 보고되지 않았기 때문일 수 있어요. 또한 템플릿 변수에 대해 쿼리된 모든 데이터는 데이터 보존 정책의 적용을 받아요. 자세한 내용은 Historical Data를 참조해요.

대시보드 레이아웃

변수가 헤더를 어지럽히지 않도록 대시보드는 작은 부분집합만 표시해요. + N 버튼을 클릭하면 대시보드에 있는 나머지 N개의 변수를 볼 수 있어요.

스크롤하면서 모든 변수를 한 번에 보고 싶다면 Expand template variables를 클릭해요.

템플릿 변수 추가하기

대시보드에 템플릿 변수를 추가하려면:

Add Variable(또는 기존 템플릿 변수가 있으면 +)을 클릭해요.
권장 템플릿 변수 목록에서 선택하거나 원하는 특정 태그를 검색해요.
이 템플릿 변수를 적용할 위젯을 선택해요.
Save를 클릭해요.

템플릿 변수 구성

템플릿 변수 측면 패널이 열려 있으면 다음을 할 수 있어요:

선택한 위젯에 이 변수를 적용하거나(또는 제거) (Select All 또는 Deselect All 옵션 참고)
필터링과 그룹화 사이를 전환
변수의 표시 이름 변경 (헤더와 위젯 쿼리에 표시)
기본 드롭다운 값 선택
드롭다운 값 미리 보기 및 검색 쿼리로 추가 구성

팀 필터 (Team filter)

태그 키가 team인 템플릿 변수는 일반 태그 값 선택기 대신 팀 필터로 렌더링돼요. 이는 대시보드와 노트북 모두에 적용돼요.

팀 필터는 다음을 추가해요:

조직의 Datadog Teams와 일치하는 팀이 없는 team 태그 값을 모두 다루는 하나의 목록.
계층 인식 선택. 팀을 선택하면 그 아래의 하위 팀도 선택돼요. 팀을 Shift+클릭하면 하위 팀 없이 팀만, 또는 팀 없이 하위 팀만 선택할 수 있어요.
팀 핸들과 팀 표시 이름 모두에서 검색.

계층 인식 선택은 변수의 태그 키가 team일 때만 나타나요. 다른 태그 키로 만든 변수는 팀 계층 개념이 없는 일반 태그 값 선택기로 렌더링돼요. 한 대시보드의 팀 변수에 계층이 있고 다른 대시보드의 팀 변수에는 계층이 없다면 각 변수의 태그 키를 비교해 보세요.

team 변수의 경우 필터는 조직의 모든 팀을 나열해요. Available Values에 설정된 값은 이 목록을 제한하는 대신 추가돼요.

다른 태그 키로 팀 필터 사용하기

일부 데이터는 team이 아닌 태그 키(예: team_attribution, attributes.team, usr.team)로 팀 소유권을 기록해요. 그런 키로 정의된 템플릿 변수는 계층이 없는 태그 문자열의 평면 목록을 제공해요.

그 데이터에 대해 계층 인식 팀 선택을 얻으려면 team 태그 키에 템플릿 변수를 정의하고 각 위젯 쿼리에서 $team.value로 선택 값을 참조해요. 변수의 태그 키가 표시되는 선택기를 결정하며, 위젯 쿼리가 필터링하는 태그 키는 별개라 일치할 필요가 없어요.

태그 키가 team인 템플릿 변수를 추가해요. 팀 필터로 렌더링돼요.
각 위젯 쿼리에서 데이터가 사용하는 태그 키로 필터링하고, 값이 들어가는 곳에 $team.value를 넣어요.

이 치환은 모든 태그 키에서 동일하게 작동해요. 평소처럼 쿼리를 작성한 다음 팀 핸들을 $team.value로 바꾸면 돼요:

위젯	팀 핸들이 있는 쿼리	`$team.value`가 있는 쿼리
Case Management (`attributes.team`)	`attributes.team:payments-platform`	`attributes.team:$team.value`
Cloud Cost (`team_attribution`)	`sum:all.cost{team_attribution:payments-platform}`	`sum:all.cost{team_attribution:$team.value}`

선택이 해석되는 방식

$team.value는 쿼리에 작성한 태그 키를 사용해 선택된 모든 팀 핸들로 확장되며 OR로 결합돼요. payments-platform과 payments-fraud 팀을 선택하면 위의 두 예시는 다음과 같이 해석돼요:

attributes.team:(payments-platform OR payments-fraud)

sum:all.cost{team_attribution:payments-platform OR team_attribution:payments-fraud}

부모 팀을 선택하면 부모와 그 아래의 모든 팀이 각각 자체 핸들로 확장돼요. 따라서 계층 선택은 team 태그 위젯과 동일한 핸들 세트로 데이터를 필터링해요. 하위 팀 없이 팀을 선택하거나 팀 없이 하위 팀을 선택해도 같은 방식으로 확장돼요. 오직 그 선택에 포함된 핸들만 포함돼요.

확장은 팀 핸들 목록이에요. 위젯이 결과를 반환하려면 데이터가 해당 핸들로 태깅되어 있어야 해요.

템플릿 변수 편집하기

대시보드 헤더의 템플릿 변수 위에 마우스를 올리고 Edit을 클릭해요. 템플릿 변수 측면 패널이 나타나요.
패널의 옵션을 사용해 변수를 사용자 지정하거나 더 많은 위젯에 변수를 적용해요.

저장된 뷰 (Saved views)

생성

대시보드의 템플릿 변수 왼쪽에 있는 Saved Views 드롭다운 메뉴를 클릭해요. 템플릿 변수 값을 업데이트해도 값이 자동으로 뷰에 저장되지는 않아요.
현재 템플릿 변수 값을 뷰에 저장하려면 Saved Views 드롭다운 메뉴에서 Save selections as view를 선택해요.
뷰에 고유한 이름을 입력하고 선택적으로 설명을 추가해요.
Save를 클릭해요.

저장된 뷰는 드롭다운 메뉴에 나타나요. 뷰를 클릭하면 이전에 저장한 템플릿 변수 값을 불러올 수 있어요.

삭제

저장된 뷰 드롭다운 메뉴를 클릭하고 원하는 저장된 뷰 위에 마우스를 올려요.
Delete View를 클릭해요.

수정

Default 뷰는 템플릿 변수의 기본값을 변경해서만 편집할 수 있어요. Default View를 편집하려면:

템플릿 위에 마우스를 올려요.
버튼이 나타나면 Edit을 클릭해요.
저장하려면 Done을 클릭해요.

다른 저장된 뷰의 템플릿 변수 값을 수정하려면:

드롭다운 메뉴에서 원하는 저장된 뷰를 선택해요.
템플릿 변수를 원하는 새 값으로 편집해요.
드롭다운 메뉴를 다시 열어요.
Save Changes를 클릭해요.

제목과 설명을 편집하려면:

드롭다운 메뉴에서 원하는 저장된 뷰 위에 마우스를 올려요.
Edit을 클릭해요.
제목 또는 설명을 수정해요.
Save를 클릭해요.

사용법 (Usage)

템플릿 변수는 위젯과 이벤트 오버레이(events overlay)에서 사용돼요.

로그, APM, RUM 쿼리

템플릿 변수는 같은 태그를 공유하므로 로그, APM, RUM 위젯에서 동작해요. 파셋을 기반으로 로그, APM, RUM 템플릿 변수를 정의할 수 있어요. 이러한 변수는 @로 시작하며 예를 들어 @http.status_code처럼 사용해요.

로그, APM, RUM 위젯에서 값의 중간에 와일드카드를 사용하거나(예: eng*@example.com) 값에 여러 와일드카드를 사용할 수 있어요(예: *prod*).

참고: 이 유형의 템플릿 변수에 Add to all을 사용하면 변수가 모든 로그, APM, RUM 위젯에 추가돼요.

위젯

위젯을 만들거나 편집할 때 기존 필터 템플릿 변수는 from 필드의 옵션으로 표시되고, 기존 group by 템플릿 변수는 by 필드 뒤의 옵션으로 표시돼요. 예를 들어 environment 템플릿 변수를 구성하면 $environment 옵션을 위젯의 동적 변수로 사용할 수 있어요.

environment 값으로 production을 선택하면 $environment 변수가 있는 위젯이 프로덕션 환경으로 동적으로 범위가 제한돼요.

템플릿 변수 값을 변경하면 대시보드 URL이 &tpl_var_<TEMPLATE_VARIABLE_NAME>=<TEMPLATE_VARIABLE_VALUE> 형식으로 값을 반영하도록 업데이트돼요. 예를 들어 $env 템플릿 변수가 prod로 변경된 대시보드에는 &tpl_var_env=prod URL 파라미터가 있어요.

값을 쿼리에 포함하려면 $<TEMPLATE_VARIABLE_NAME>.value 구문으로 추가해요. 예를 들어 service라는 템플릿 변수가 있다면 env:staging-$service.value처럼 사용해요.

템플릿 변수 필드 위에 마우스를 올리면 해당 변수를 사용하는 위젯이 대시보드에서 강조 표시된 것을 한눈에 볼 수 있어요.

연결된 템플릿 변수 (Associated template variables)

템플릿 변수 값을 선택할 때 연결된 값이 선택기 상단에 표시돼요. 연결된 값은 페이지에서 선택된 다른 템플릿 변수 값에서 계산되며, 별도의 구성 없이 관련 값을 쉽게 식별해 줘요.

텍스트

텍스트 기반 위젯에서는 $<TEMPLATE_VARIABLE_NAME>으로 템플릿 변수의 태그/속성과 값을, $<TEMPLATE_VARIABLE_NAME>.key로 키를, $<TEMPLATE_VARIABLE_NAME>.value로 값을 표시할 수 있어요. 이것은 영숫자가 아닌 문자 뒤에 올 수 있고, 공백 또는 #, $, %, =, ;, ", (, ), [, ], {, }, ^, *, +, |, ? 중 하나가 뒤따를 수 있어요.

참고: 템플릿 변수 뒤에서는 와일드카드 구문이 지원되지 않아요.

예를 들어 env라는 템플릿 변수가 태그/속성 environment를 가지며 선택 값이 dev일 때:

$env는 environment:dev를 표시해요
$env.key는 environment를 표시해요
$env.value는 dev를 표시해요
$env*는 정확한 값 dev*를 찾으며 dev{dynamic-wildcard-value}가 아니에요

이벤트 오버레이 (Events overlay)

이벤트 오버레이 검색을 템플릿 변수와 함께 사용하면 대시보드의 메트릭과 특정 태그를 공유하는 이벤트를 찾을 수 있어요. 이벤트 오버레이 검색은 개별 그래프를 통해 적용돼요.

대시보드 템플릿 변수의 값은 이벤트 검색 필드에서 $<TEMPLATE_VARIABLE_KEY>.value 구문으로 직접 캡처할 수 있어요.

참고: 대시보드 템플릿 변수는 이벤트 태그가 아닌 메트릭 태그여야 해요.

대시보드

대시보드에서 템플릿 변수로 이벤트를 검색할 때는 다음 형식을 사용해요:

<TAG_KEY>:$<TEMPLATE_VARIABLE_NAME>.value

예를 들어 region 템플릿 변수 값이 us-east1일 때 region:$region.value를 검색하면 region:us-east1로 태깅된 이벤트가 표시돼요. 또한 이벤트의 시점이 그래프에서 분홍색 막대로 표시돼요.

여러 템플릿 변수로 검색하려면 쉼표를 사용해요. 예: role:$role.value,env:$env.value

참고: 검색을 위해 enter를 누르면 $region.value가 템플릿 변수 드롭다운 메뉴의 값으로 업데이트돼요.

위젯

위젯에서 다음 형식으로 템플릿 변수를 사용해 이벤트의 시점을 오버레이해요:

$<TEMPLATE_VARIABLE_NAME>

예를 들어 이벤트 오버레이 검색 상자에 $region을 입력해요. 이는 region 템플릿 변수 드롭다운 메뉴의 값과 일치하는 이벤트를 검색해요.