Zipkin 데이터 소스 문제 해결

Zipkin 데이터 소스 문제 해결 (Troubleshoot Zipkin data source issues)

이 문서는 Zipkin 데이터 소스를 구성하거나 사용할 때 겪을 수 있는 일반적인 문제(연결 실패, 쿼리 오류, JSON 업로드 문제, 구성 문제)의 해결책을 제공해요. 구성 방법은 "Configure Zipkin" 문서를 참고하세요.

출처: 문서

본문

연결 오류

error reading settings: url is empty 증상: Save & test가 즉시 실패, 건강 검사(Health check)가 오류 반환. 해결: 데이터 소스 설정에서 URL 필드가 비어있지 않은지 확인하고 http://localhost:9411 같은 Zipkin 인스턴스의 전체 URL을 입력해요.

"request failed: 404 Not Found" 또는 기타 HTTP 상태 오류 증상: Save & test가 HTTP 상태 오류로 실패, 트레이스 쿼리 오류.

Cause Solution
잘못된 URL 또는 포트 URL과 포트를 확인. 기본 Zipkin 포트는 9411. 실수로 Jaeger 포트(16686)를 쓰지 않았는지 확인.
/api/v2 경로 누락 Zipkin 데이터 소스는 /api/v2/services, /api/v2/traces 등을 호출. 구성된 URL에서 이 엔드포인트에 접근 가능한지 확인.
리버스 프록시 설정 오류 리버스 프록시를 쓰면 Zipkin API로 요청을 올바르게 전달하는지 확인.
인증 실패 Zipkin 인스턴스가 인증을 요구하면 자격 증명이 올바른지 확인.

error creating http client 또는 TLS 오류 해결: HTTPS를 쓰면 TLS 인증서가 유효하고 Grafana 서버에서 신뢰되는지 확인하고, Additional settings > Advanced HTTP settings에서 TLS 설정을 구성하며, 자체 서명 인증서는 CA 인증서를 Grafana 서버 신뢰 저장소에 추가하거나 Skip TLS Verify를 켜요(프로덕션 비권장).

Save & test 타임아웃

Cause Solution
Zipkin 인스턴스 다운 Zipkin 인스턴스가 실행 중이고 Grafana 서버에서 접근 가능한지 확인.
방화벽 또는 네트워크 규칙 Grafana 서버가 Zipkin 인스턴스에 도달할 수 있는지, 방화벽이 구성된 포트의 아웃바운드 트래픽을 허용하는지 확인.
DNS 해석 실패 URL의 호스트 이름이 Grafana 서버에서 올바르게 해석되는지 확인.

Grafana Cloud에서 비공개 Zipkin 인스턴스에 접근하려면 Private data source connect를 구성해요.

쿼리 편집기 오류

"Failed to load spans from Zipkin" — 쿼리 편집기에 오류, Traces 단계 선택기가 서비스·스팬·트레이스를 채우지 못해요. 프론트엔드가 Zipkin API 엔드포인트(/api/v2/services, /api/v2/spans, /api/v2/traces)에 도달할 수 없을 때 발생해요. 해결: Zipkin 인스턴스가 실행 중인지 확인하고, 엔드포인트를 직접 테스트하며(curl http://<ZIPKIN_URL>/api/v2/services), Grafana 서버가 Zipkin API에 도달할 수 있는지 확인하고, 서버 로그에서 An error occurred while doing a resource call을 찾아보세요.

"An error occurred within the plugin" — Zipkin 플러그인 백엔드에서 내부 오류 발생 시 반환하는 일반 오류로, 실제 세부 내용은 Grafana 서버 로그에만 있어요. 해결: debug logging을 활성화하고, 서버 로그에서 An error occurred while doing a resource call 또는 An error occurred while processing response from resource call 메시지를 확인하며, Zipkin 인스턴스가 정상이고 API 요청에 응답하는지 확인해요.

"No data" 또는 빈 결과

Cause Solution
잘못된 트레이스 ID 트레이스 ID가 올바른지 확인. Zipkin 트레이스 ID는 16 또는 32자 16진수 문자열.
빈 트레이스 ID Trace ID 필드가 비어있지 않은지 확인. 백엔드는 유효하지 않거나 빈 traceId를 가진 쿼리를 거부.
시간 범위에 데이터 없음 대시보드나 Explore 시간 범위를 넓혀요. 트레이스는 선택한 시간 범위 안에 있어야 선택기가 찾을 수 있음.
트레이스 만료 Zipkin이 보존 설정에 따라 오래된 데이터를 제거했을 수 있음. Zipkin 스토리지 구성을 확인.
등록된 서비스 없음 최상위 레벨에 "No traces found"가 보이면 인스턴스에 데이터가 없을 수 있음. 데이터가 수집되는지 확인.

업로드 오류

"JSON is not valid Zipkin format"

Cause Solution
잘못된 JSON 문법 JSON linter로 검증. 흔한 문제: 후행 쉼표, 따옴표 누락, 닫히지 않은 괄호.
잘못된 JSON 구조 파일은 단일 객체가 아닌 스팬 객체의 JSON 배열([{...}, {...}])이어야 함. Zipkin v2 span 포맷 참고.
잘못된 파일 유형 .json 파일을 업로드하는지 확인.

unsupported query type upload. only available in frontend mode — 업로드 쿼리는 Explore에서만 동작해요. 업로드가 백엔드가 아닌 브라우저에서 처리되므로 대시보드 패널이나 알림 규칙에서는 쓸 수 없어요. 해결: 대시보드에 표시해야 한다면 업로드한 트레이스의 트레이스 ID와 함께 TraceID 쿼리 타입을 사용하세요. 이 방식은 트레이스가 Zipkin 인스턴스에 존재해야 해요.

구성 오류

"Invalid time shift. See tooltip for examples." — trace to logs 또는 trace to metrics 구성에서 오류. 해결: 유효한 시간 단위 형식(5s, 1m, 3h, -30m)을 사용하고, 과거로 이동하려면 음수 값을 사용하며(-1h), 값은 숫자 + 시간 단위(s, m, h) 형식이어야 해요.

Trace to logs 링크가 나타나지 않음

Cause Solution
스팬에 태그 없음 trace to logs 설정에 구성된 태그가 링크가 나타나려면 스팬 속성에 존재해야 함. 스팬에 예상 태그가 있는지 확인.
로그 데이터 소스 미구성 대상 로그 데이터 소스(Loki, Elasticsearch, Splunk, OpenSearch, FalconLogScale, Google Cloud Logging, VictoriaMetrics Logs)가 구성되고 동작하는지 확인.
커스텀 쿼리 변수 미해석 커스텀 쿼리를 쓰면 모든 변수가 비어있지 않은 값으로 해석될 때만 링크가 나타남. 스팬에 참조된 태그가 있는지 확인.
잘못된 데이터 소스 유형 trace to logs 데이터 소스는 지원되는 로그 데이터 소스여야 함. 다른 유형은 드롭다운에 나타나지 않음.

Trace to metrics 링크가 나타나지 않음 해결: 대상 메트릭 데이터 소스가 구성되고 동작하는지, 연결된 쿼리가 유효한 쿼리 문법으로 정의됐는지, 쿼리의 $__tags 키워드가 스팬에 존재하는 태그로 매핑되는지 확인해요.

템플릿 변수 오류

쿼리에서 변수 값이 치환되지 않음 — 트레이스 ID 필드에 실제 값 대신 ${traceId} 같은 변수 문법이 표시되고, 변수를 쓰면 쿼리가 결과 없음. 해결: 대시보드를 열고 Edit 클릭, Dashboard options 아이콘으로 사이드바 열기, Variables 섹션 펼치기, 변수가 정의됐는지 확인, 변수 이름이 쿼리의 문법과 일치하는지 확인(변수 이름은 대소문자 구분), 변수에 값이 선택되거나 입력됐는지 확인, 텍스트 박스 변수는 뷰어가 값을 입력했는지 확인해요.

디버그 로깅 활성화

  1. 구성 파일에서 Grafana 로그 레벨을 debug로 설정해요:
[log]
level = debug
  1. /var/log/grafana/grafana.log(또는 구성된 로그 위치)에서 로그를 확인해요.
  2. 요청·응답 세부 정보를 포함하는 Zipkin 특유 항목을 찾아요: Failed to close response body, An error occurred while doing a resource call, An error occurred while processing response from resource call.
  3. 트러블슈팅 후 과도한 로그를 피하기 위해 로그 레벨을 info로 초기화해요.

추가 도움

더 알아보기 (Learn more)