Loki 애노테이션
Loki 애노테이션 (Loki annotations)
애노테이션은 그래프 위에 풍부한 이벤트 정보를 오버레이해요. Loki 데이터 소스에서 애노테이션은 로그 쿼리로 만들어져요: 대시보드 시간 범위 내에서 LogQL 쿼리가 반환하는 각 로그 줄이 애노테이션이 되므로, 로그 이벤트를 대시보드의 나머지 데이터와 상호 연관지을 수 있어요.
출처: 문서
본문
Loki 애노테이션이 작동하는 방식
별도의 쿼리 언어로 애노테이션을 만드는 데이터 소스와 달리, Loki 애노테이션은 다른 곳에서 쓰는 것과 같은 LogQL 로그 쿼리를 사용해요. Grafana가 대시보드 시간 범위에 대해 로그 쿼리를 실행하고, 반환된 각 로그 줄을 애노테이션으로 바꿔요. 기본적으로 Grafana는 로그 콘텐츠를 애노테이션 텍스트로, 로그 스트림 라벨을 태그로 사용하므로 추가 매핑을 만들 필요가 없어요. 로그 쿼리만 애노테이션 소스로 사용할 수 있고, 메트릭 쿼리는 지원되지 않아요.
애노테이션 쿼리 만들기
대시보드에 Loki 애노테이션을 추가하려면 대시보드 설정의 Annotations에 Loki 데이터 소스로 새 쿼리를 추가하면 돼요. 애노테이션 쿼리 에디터는 다음 필드를 제공해요.
| 필드 | 설명 |
|---|---|
| Query | 애노테이션할 로그 줄을 선택하는 LogQL 로그 쿼리 |
| Title | 선택. 애노테이션 제목의 리터럴 이름 또는 템플릿. {{label}}로 라벨 참조(예: {{level}}) |
| Tags | 선택. 콤마로 구분된 라벨 키 목록을 애노테이션 태그로 사용(예: app,level). 비어 있으면 Grafana가 로그 스트림 라벨을 태그로 사용 |
| Text | 선택. 애노테이션 텍스트의 리터럴 문자열 또는 템플릿. {{label}}로 라벨 참조. 비어 있으면 Grafana가 로그 줄 콘텐츠를 텍스트로 사용 |
템플릿 필드는 파싱된 필드를 포함해 각 반환 로그 줄의 라벨에 대해 해석돼요. 인덱스 라벨이 아닌 값을 참조하려면 logfmt나 json 같은 파서를 쿼리에 추가해 그 필드를 사용 가능하게 만드세요.
예시
배포 이벤트를 애노테이션하려면 다음 값으로 애노테이션 쿼리를 구성하세요.
| 필드 | 값 |
|---|---|
| Query | {app="deploy-bot"} |= "deployed" |
| Title | {{app}} deployed |
| Tags | app,env |
| Text | {{message}} |
일치하는 각 로그 줄은 배포 앱으로 제목이 붙고, app과 env 라벨로 태그되며, 파싱된 message 필드로 설명되는 애노테이션이 돼요. Text 템플릿이 파싱된 필드를 참조하므로 쿼리에 파서가 필요해요. 예:
{app="deploy-bot"} |= `deployed` | logfmt
애노테이션 문제 해결
- 애노테이션이 나타나지 않음: 쿼리가 시간 범위 내 데이터를 반환하는지, 데이터 소스가 올바른지, 토글이 활성화됐는지 확인하세요.
- 애노테이션 과다: 쿼리 결과를 좁혀 반환되는 로그 줄 수를 줄이세요.