Loki 데이터 소스 문제 해결
Loki 데이터 소스 문제 해결 (Troubleshoot Loki data source issues)
이 문서는 Loki 데이터 소스를 구성하거나 사용할 때 겪을 수 있는 일반적인 문제에 대한 해결책을 제공해요. 연결, 쿼리, 성능, 템플릿 변수, 파생 필드, 라이브 테일링, LBAC 오류로 나눠 설명합니다.
출처: 문서
본문
참고: 이 가이드는 Grafana의 Loki 데이터 소스(Loki 연결, 쿼리 실행, 기능 구성)를 다뤄요. Loki 서비스 자체의 문제 해결은 다루지 않아요. Loki 배포(수집·쿼리 성능 포함) 도움이 필요하면 Loki 문서의 "Manage and debug errors"를 참고하세요.
연결 오류
Grafana가 Loki 서버에 도달할 수 없을 때 발생해요.
Save & test 실패
| 원인 | 해결 |
|---|---|
| 잘못된 URL 또는 포트 | URL 설정 확인. Loki는 기본적으로 3100 포트 수신. 예: http://localhost:3100 |
| URL에 API 경로 포함 | 기본 Loki URL만 입력. /loki/api/v1/push 같은 API 경로는 Loki를 쿼리하지 않고 로그를 보내므로 추가하지 말 것 |
| Grafana Cloud에서 localhost URL | Grafana Cloud에서 localhost/프라이빗 주소는 여러분의 네트워크가 아니라 Grafana 서버를 가리킴. 자체 호스팅 Loki에 도달하려면 PDC 사용 |
| 테넌트 헤더 누락 | auth_enabled: true인 멀티 테넌트 Loki는 X-Scope-OrgID 커스텀 HTTP 헤더에 테넌트 ID 추가 |
| 네트워크/방화벽 차단 | Grafana 서버가 Loki 서버에 도달할 수 있고 방화벽 규칙이 연결을 허용하는지 확인 |
| 인증 실패 | 데이터 소스 구성의 자격 증명, 토큰, TLS 인증서 확인. Grafana Cloud Loki는 접근 정책 토큰에 logs:read 스코프가 포함됐는지 확인 |
| TLS 검증 실패 | Loki가 자체 서명 인증서를 쓰면 With CA cert로 CA 인증서를 추가하거나, 테스트용으로 Skip TLS verify 활성화 |
쿼리 오류
데이터 없음 또는 빈 결과
| 원인 | 해결 |
|---|---|
| 시간 범위에 로그 없음 | 대시보드 시간 범위를 넓히거나 그 기간에 Loki에 로그가 있는지 확인 |
| 라벨 선택기가 스트림과 일치하지 않음 | 쿼리 에디터의 라벨 브라우저로 스트림 선택기 라벨·값 확인 |
| 로그가 보존 기간 초과 | 기대하는 로그가 Loki에 구성된 보존 기간 내인지 확인 |
쿼리 타임아웃 또는 "too many outstanding requests"
- 쿼리를 단순화하고 시간 범위를 줄이며, 데이터 소스 타임아웃 설정을 확인하세요. Loki 서버 부하도 점검하세요.
"maximum of series reached for a single query"
- 쿼리 반환 시리즈 수를 줄이기 위해 라벨 매처를 좁히고 집계하세요.
성능 문제
쿼리가 느리거나 속도 제한
- 쿼리를 최적화하고, 스트림 선택기를 좁히며, 자주 쓰는 쿼리에 recording rules를 사용하고, Loki 태스크/리소스를 점검하세요.
템플릿 변수 오류
변수가 값을 반환하지 않음
- 쿼리 유형(Label names/Label values), 라벨 이름, 스트림 선택기 설정을 확인하세요.
파생 필드 및 로그-트레이스 링크 문제
- 파생 필드/트레이스 링크가 나타나지 않음: 정규식에 캡처 그룹이 포함됐는지, 대상 데이터 소스가 올바른지 확인하세요.
- 트레이스 링크가 열리지만 트레이스 없음: 트레이스가 대상 데이터 소스(예: Tempo)에 이미 수집되어 있어야 링크가 해석돼요.
- 프로비저닝된 데이터 소스에서 파생 필드 편집 불가: 프로비저닝으로 만든 데이터 소스는 UI에서 읽기 전용이라 구성 페이지에서 파생 필드를 변경할 수 없어요.
- 단일 링크가 두 개 이상의 필드 값 필요: 파생 필드는 로그 줄당 하나의 값을 생성하므로 여러 라벨이나 캡처 그룹을 하나의 필드/링크로 결합할 수 없어요. 표시할 값마다 별도의 파생 필드를 만드세요.
라이브 테일링 문제
라이브 테일링이 로그를 스트리밍하지 않음
라이브 테일링은 브라우저-Grafana, Grafana-Loki 사이의 WebSocket 연결에 의존해요. 리버스 프록시가 자주 이 연결을 차단해요. 프록시가 WebSocket 업그레이드 헤더(Upgrade, Connection)를 전달하고 타임아웃이 충분히 긴지 확인하세요. Apache2/NGINX 구성 예시는 쿼리 에디터 문서를 참고하세요.
라벨 기반 접근 제어 (LBAC) 문제
LBAC는 라벨에 따라 팀이 쿼리할 수 있는 로그를 필터링해요. Grafana Cloud와 Grafana Enterprise에서 사용할 수 있으며(Enterprise는 Grafana Enterprise Logs(GEL) 필요), LBAC를 활성화할 수 없거나 팀이 예상보다 많은 로그를 보는 경우 다음을 확인하세요.
프로비저닝된 데이터 소스에서 LBAC 활성화 불가
참고: 프로비저닝되거나 자동 프로비저닝된 Loki 데이터 소스에서는 LBAC를 활성화할 수 없어요. LBAC 데이터 소스 프로비저닝은 지원되지 않아요.
LBAC를 사용하려면 새 Loki 데이터 소스를 수동으로 만들고, Cloud Access Policy(CAP) 토큰을 비밀번호로 사용하는 기본 인증으로 구성하세요. 프로비저닝된 데이터 소스와 같은 Loki 엔드포인트를 가리키게 하고, 새 데이터 소스의 Permissions 탭에서 LBAC 규칙을 정의하세요.
팀이 여전히 모든 로그를 쿼리함
상세 및 제한 사항은 "데이터 소스용 LBAC"를 참고하세요.
디버그 로깅 활성화
문제 해결을 위해 상세 오류 정보를 캡처하려면 Grafana 로그 레벨을 DEBUG로 설정하세요.