Loki 템플릿 변수

Loki 템플릿 변수 (Loki template variables)

메트릭 쿼리에 서버, 애플리케이션, 센서 이름 같은 세부 정보를 하드코딩하는 대신 변수를 사용할 수 있어요. Grafana는 이 변수를 대시보드 상단의 드롭다운 선택 상자에 나열해 대시보드에 표시되는 데이터를 쉽게 바꿀 수 있게 해줘요. Grafana는 이런 변수를 템플릿 변수라고 부릅니다.

출처: 문서

본문

쿼리 변수 사용 (Use query variables)

Query 유형의 변수는 Loki에서 라벨 또는 라벨 값 목록을 쿼리하는 데 도움을 줘요. Loki 데이터 소스는 주어진 변수에 기대되는 값 유형을 선택하는 폼을 제공해요.

쿼리 유형	예시 라벨	예시 스트림 선택기	반환 목록
Label names	필요 없음	필요 없음	라벨 이름
Label values	label	(없음)	`label`에 대한 라벨 값
Label values	label	로그 스트림 선택기	지정된 로그 스트림 선택기의 `label`에 대한 라벨 값

쿼리 변수 예시

app 라벨의 값을 나열하는 변수를 만들려면 쿼리 유형을 Label values로 하고 라벨에 app을 입력하면 돼요.

쿼리에서 변수를 이름 앞에 $를 붙여 참조하세요. 단일 값 변수는 정확 매칭을 사용해요:

{app="$app"}

변수가 Multi-value나 Include All을 활성화하면 Grafana가 선택된 값을 payments|checkout 같은 정규식으로 결합해요. 정규식 매칭 연산자 =~를 사용해 쿼리가 선택된 값 중 하나와 일치하게 하세요:

{app=~"$app"}

변수 값 형식화

기본적으로 Loki 데이터 소스는 변수 설정에 따라 변수 값을 형식화해요. 이 기본값은 정규식 매칭 연산자 =~에 적합하지만, Grafana가 이스케이프하는 문자가 포함된 커스텀/정적 값을 넣거나 정규식이 아닌 컨텍스트에 값을 넣으면 예기치 않은 결과가 나올 수 있어요. 형식을 제어하려면 변수 문법에서 형식 옵션을 사용하세요:

문법	결과
`${app:raw}`	이스케이프 없이 값 삽입. 그대로 통과해야 하는 커스텀/정적 값에 사용
`${app:pipe}`	정규식 이스케이프 없이 여러 값을 `\|`로 결합
`${app:regex}`	값을 정규식용으로 이스케이프하고 `\|`로 결합

예를 들어 정확 매칭 선택기에서 raw 커스텀 값을 사용하려면:

{app="${app:raw}"}

Ad hoc 필터 사용

Loki는 ad hoc 필터를 지원해요. 각 쿼리를 편집하지 않고 Grafana가 모든 Loki 쿼리에 자동으로 적용하는 여러 키/값 필터를 지정할 수 있어요. 예를 들어 level = error ad hoc 필터를 추가하면 Grafana가 대시보드의 모든 Loki 쿼리의 스트림 선택기에 매처를 추가하여, {app="payments"} 같은 쿼리가 {app="payments", level="error"}로 실행돼요.

Loki 메트릭 쿼리에 $__auto 변수 사용

Loki 메트릭 쿼리에서 $__auto 변수를 사용하는 것을 고려하세요. 레인지 쿼리에서는 step 값으로, 인스턴트 쿼리에서는 선택한 시간 범위의 값(시작·종료 시간에서 계산)으로 자동 치환돼요. 레인지 집계의 범위로 사용하세요:

sum(rate({app="payments"} |= `error` [$__auto]))

참고: 메트릭 쿼리의 범위에는 $__range보다 $__auto를 선호하세요. $__range 변수는 선택한 전체 시간 범위로 해석되므로, [$__range]처럼 범위 벡터로 사용하면 각 데이터 포인트가 전체 창을 집계해 의도보다 훨씬 많은 데이터를 스캔하고 더 멀리 되돌아볼 수 있어요.

알려진 제한 사항

Loki 데이터 소스에서 템플릿 변수를 사용할 때 다음 제한을 염두에 두세요: 일부 변수 유형/형식은 특정 상황에서 예기치 않은 결과를 낼 수 있어요.

Loki의 라벨 추출과 인덱싱

라벨은 Loki가 로그를 집계·쿼리하는 핵심이에요. 라벨은 로그 항목에 컨텍스트 정보를 추가하는 키-값 쌍이며, Loki는 이를 사용해 로그 데이터를 효율적으로 구성·필터링·검색해요.

라벨 추출 (Label extraction)

Loki는 로그를 수집할 때 정규식을 사용해 로그 줄에서 라벨을 추출하므로, 로그 형식과 일치하는 커스텀 패턴을 정의할 수 있어요. 예를 들어 다음 로그 줄이 주어졌을 때:

2023-07-25 12:34:56 INFO: Request from IP A.B.C.D to endpoint /api/data

로그 레벨(INFO), IP 주소(A.B.C.D), 엔드포인트(/api/data)를 라벨로 추출하는 정규식을 정의할 수 있어요. 그런 다음 그 라벨들로 로그 항목을 필터링·집계할 수 있어요.

인덱스 라벨 (Index labels)

Loki는 추출된 라벨을 인덱싱해요. 인덱스는 라벨을 로그 항목에 매핑하므로, Loki가 전체 데이터셋을 스캔하지 않고 라벨별로 로그를 검색할 수 있어요. 예를 들어 job 라벨이 애플리케이션의 서비스를 나타낸다면 Loki는 각 job의 로그를 별도로 인덱싱해서 단일 job을 빠르게 쿼리할 수 있어요. Loki 인덱스 라벨을 Grafana 템플릿 변수와 결합해 동적 쿼리를 만들 수 있어요. 템플릿 변수로 job 이름, 인스턴스 ID, 심각도 수준 같은 라벨별 로그를 선택·필터링해 대화형으로 로그 데이터를 탐색·시각화할 수 있어요.

Loki 템플릿 변수