Jaeger 데이터 소스 트러블슈팅

Jaeger 데이터 소스를 구성하거나 사용할 때 겪을 수 있는 흔한 문제에 대한 해결책을 정리한 문서예요. 연결 오류, 인증 오류, 쿼리 오류, 의존성 그래프, gRPC 엔드포인트 문제를 다룹니다.

출처: Troubleshoot Jaeger data source issues

본문

연결 오류 (Connection errors)

Grafana가 Jaeger 인스턴스에 도달할 수 없을 때 발생해요.

"Connection refused" 또는 시간 초과 오류:

증상: Save & test가 연결 오류로 실패. 쿼리가 네트워크 오류로 실패. 서비스와 작업 드롭다운이 로드 안 됨.

원인	해결
Jaeger가 실행 중이지 않음	Jaeger가 구성된 URL에서 실행되고 접근 가능한지 확인.
잘못된 URL	데이터 소스 구성의 URL 설정 확인. 기본 Jaeger 쿼리 엔드포인트는 `http://localhost:16686`.
방화벽 차단	방화벽 규칙이 Grafana 서버에서 Jaeger 엔드포인트로의 트래픽을 허용하는지 확인.
네트워크 분리	Grafana Cloud가 프라이빗 Jaeger 인스턴스에 접근할 때 Private data source connect 구성.

"request failed: 404 Not Found":

증상: Save & test가 404 오류 반환. 쿼리가 "request failed" 메시지로 실패.

Jaeger URL에 /api 같은 끝 경로가 포함되지 않았는지 확인. 올바른 URL은 기본 엔드포인트, 예: http://localhost:16686.
Jaeger 쿼리 서비스가 실행 중이고 예상 포트에서 수신 중인지 확인.
리버스 프록시를 사용한다면 프록시가 요청을 올바른 Jaeger 엔드포인트로 전달하는지 확인.

TLS 오류:

증상: Save & test 중 인증서 검증 오류. x509 또는 인증서 검증 언급 오류.

TLS 인증서가 유효하고 만료되지 않았는지 확인.
프라이빗 CA를 사용한다면 데이터 소스 Additional settings에서 CA 인증서가 구성되었는지 확인.
테스트용으로 데이터 소스 설정에서 임시로 Skip TLS verify를 켤 수 있음. 프로덕션에선 사용하지 마세요.
Server name 설정이 인증서의 Common Name 또는 Subject Alternative Name과 일치하는지 확인.

시간 초과 오류:

증상: 쿼리가 오래 걸린 뒤 실패. 오류가 시간 초과 언급.

Additional settings > Timeout에서 시간 초과 값 증가.
Grafana와 Jaeger 사이의 네트워크 지연이 허용 가능한지 확인.
Jaeger 쿼리 서비스가 과부하되지 않았는지 확인.

인증 오류 (Authentication errors)

자격 증명이 유효하지 않거나 없을 때 발생해요.

"401 Unauthorized" 또는 "403 Forbidden":

증상: Save & test가 인증 오류로 실패. 쿼리가 접근 거부 메시지 반환. 서비스와 작업이 드롭다운에서 로드 안 됨.

원인	해결
잘못된 자격 증명	데이터 소스 구성의 User와 Password 값 확인.
인증 누락	Jaeger가 인증을 요구하면 적절한 인증 방법 토글.
잘못된 커스텀 헤더	Additional settings에서 커스텀 헤더 이름과 값 확인.
OAuth 전달 문제	Forward OAuth identity를 사용한다면 업스트림 OAuth 제공자가 올바르게 구성되었는지 확인.

쿼리 오류 (Query errors)

Jaeger에 대해 쿼리를 실행할 때 발생해요.

"traceID is empty":

증상: TraceID 쿼리 유형 사용 시 "traceID is empty"로 쿼리 실패.

Trace ID 필드에 유효한 트레이스 ID 입력.
트레이스 ID가 유효한 16진수 문자열인지 확인.
템플릿 변수를 사용한다면 변수가 비어 있지 않은 값으로 해석되는지 확인.

검색 결과에 데이터 없음:

증상: 검색 쿼리가 트레이스를 반환하지 않음. 트레이스 목록이 비어 있음.

원인	해결
시간 범위에 데이터 없음	대시보드/Explore 시간 범위 확장. 선택 기간에 Jaeger에 트레이스가 존재하는지 확인.
서비스/작업이 존재하지 않음	선택한 서비스와 작업 이름이 Jaeger의 것과 일치하는지 확인.
태그 문법 오류	태그가 `logfmt` 형식인지 확인: `error=true db.statement="select * from User"`.
기간 형식 오류	지원 기간 형식 사용: `1.2s`, `100ms`, `500us`.
Limit가 너무 낮음	Limit 값 증가 또는 기본값 위해 비워 둠.

"The JSON file uploaded is not in a valid Jaeger format":

증상: 트레이스 파일 가져오기가 형식 오류로 실패.

JSON 파일이 루트 수준에 data 배열이 있는 Jaeger 트레이스 형식을 따르는지 확인.
파일이 data 배열에 하나 이상의 트레이스 객체를 포함하는지 확인.
JSON 린터로 JSON 문법 검증.

기대 형식:

{
  "data": [
    {
      "traceID": "",
      "spans": [...],
      "processes": {...}
    }
  ]
}

의존성 그래프 오류 (Dependency graph errors)

의존성 그래프 쿼리 유형과 관련된 오류예요.

빈 의존성 그래프:

증상: 의존성 그래프 쿼리가 노드 또는 엣지를 반환하지 않음. Node Graph 패널이 비어 있음.

원인	해결
의존성 데이터 없음	Jaeger가 서비스 의존성 정보를 수집·처리하는지 확인.
시간 범위가 너무 좁음	대시보드 시간 범위 확장. 의존성은 선택 기간에 걸쳐 계산됨.
Jaeger 스토리지 백엔드	일부 Jaeger 스토리지 백엔드는 의존성 쿼리를 지원하지 않을 수 있음. 스토리지별 세부 사항은 Jaeger 문서 참고.

gRPC 엔드포인트 오류

gRPC 쿼리 엔드포인트를 사용할 때 발생해요.

gRPC 쿼리 실패:

증상: 쿼리가 gRPC 엔드포인트를 사용하지 않음. 검색·서비스·작업 쿼리가 여전히 REST API를 사용.

Grafana에서 jaegerEnableGrpcEndpoint 기능 플래그가 활성화되었는지 확인. 이 기능은 실험적.
Grafana Cloud 고객은 접근을 요청하려면 지원팀에 문의.
기능 플래그가 활성화되어도 검색과 의존성 그래프 쿼리는 현재 REST 엔드포인트를 사용. gRPC를 사용하는 것은 서비스 검색, 작업 검색, 트레이스 ID 쿼리뿐.

디버그 로깅 활성화 (Enable debug logging)

자세한 오류 정보를 잡으려면:

구성 파일에서 Grafana 로그 레벨을 debug로 설정:

[log]
level = debug

문제를 재현.
/var/log/grafana/grafana.log(또는 구성된 로그 위치)에서 로그 검토.
요청 URL, 응답 상태 코드, 오류 상세가 포함된 Jaeger 특정 항목 확인.
과도한 로그 볼륨을 피하려면 트러블슈팅 후 info로 재설정.

추가 도움 (Get additional help)

Grafana 커뮤니티 포럼에서 유사한 문제 확인.
Grafana GitHub 이슈에서 Jaeger 데이터 소스 관련 알려진 버그 검토.
Jaeger 문서에서 서비스별 지침 참고.
Enterprise, Cloud Pro, Cloud Advanced 사용자라면 Grafana Support에 문의.

이슈 보고 시 포함할 것: Grafana 버전, Jaeger 버전, 오류 메시지(민감 정보는 redact), 재현 단계, 관련 데이터 소스 구성(자격 증명은 redact).

Jaeger 데이터 소스 트러블슈팅