Parca 데이터 소스 트러블슈팅

Parca 데이터 소스 트러블슈팅

Parca 데이터 소스를 구성하거나 사용할 때 겪을 수 있는 흔한 문제에 대한 해결책을 정리한 문서예요. 연결 오류, 쿼리 오류, 쿼리 편집기, 템플릿 변수 문제를 다룹니다. 참고로 이 플러그인은 비권장(deprecated)이며 2027년 1월 2일에 지원이 종료될 예정이에요.

출처: Troubleshoot Parca data source issues

본문

⚠️ 경고: 이 플러그인은 비권장이며 중요한 보안 업데이트만 받을 거예요. 지원은 2027년 1월 2일에 종료될 예정이에요.

구성 지침은 Parca 데이터 소스 구성 문서를 참고하세요.

연결 오류 (Connection errors)

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

"Save & test" 실패:

증상: 데이터 소스 테스트가 시간 초과되거나 오류 반환. Parca 서버에 연결할 수 없음.

원인 해결
잘못된 URL URL이 Parca HTTP 엔드포인트를 가리키는지 확인(예: http://localhost:7070). Grafana는 gRPC-Web으로 연결.
Parca가 실행 중이지 않음 Parca 인스턴스가 실행 중이고 Grafana 서버에서 접근 가능한지 확인.
방화벽 차단 방화벽 규칙이 구성된 포트에서 Grafana에서 Parca 서버로의 아웃바운드 트래픽을 허용하는지 확인.
TLS 잘못 구성 HTTPS를 사용한다면 Grafana와 Parca 양쪽에서 TLS 인증서가 올바르게 구성되었는지 확인.

연결이 성공하면 상태 점검은 "Data source is working"을 표시해요. 상태 점검은 Parca 서버에서 사용 가능한 프로필 유형을 쿼리하므로 연결이나 인증 문제가 있으면 실패해요.

Connection refused 또는 시간 초과 오류:

증상: 쿼리가 네트워크 오류로 실패. 간헐적 연결 문제.

  • Grafana 서버에서 Parca 엔드포인트로의 네트워크 연결 확인.
  • Parca 서버가 정상이고 요청에 응답하는지 확인.
  • Grafana Cloud라면 프라이빗 Parca 인스턴스에 접근할 때 Private data source connect 구성.

쿼리 오류 (Query errors)

Parca 데이터 소스에 대해 쿼리를 실행할 때 발생해요.

"Invalid report type" 또는 "try updating Parca to v0.19+":

증상: 쿼리가 "invalid report type"을 포함한 오류로 실패. 오류 메시지가 Parca v0.19+ 업데이트 제안. 플레임 그래프 데이터가 로드 안 됨.

  • Parca 서버를 v0.19 이상으로 업그레이드. 이 오류는 이전 Parca 버전이 Grafana가 요구하는 플레임 그래프 Arrow 형식을 지원하지 않기 때문에 발생.

"Unknown report type returned from query. update parca":

증상: 프로필 쿼리가 이 정확한 오류 메시지로 실패. 메트릭 쿼리는 여전히 성공할 수 있음.

  • Parca 서버 업그레이드. 이 오류는 Parca 서버가 Grafana가 인식하지 못하는 응답 형식을 반환할 때 발생. 최신 Parca 버전 업데이트로 해결.

"No data" 또는 빈 결과:

증상: 쿼리가 오류 없이 실행되지만 데이터 반환 없음. 플레임 그래프/메트릭 패널이 "No data" 표시.

원인 해결
프로필 유형 미선택 드롭다운 메뉴에서 프로필 유형 선택. 이 필드는 필수 — 없으면 쿼리가 조용히 빈 데이터 반환.
시간 범위에 데이터 없음 대시보드 시간 범위 확장 또는 선택 기간에 프로파일링 데이터 존재 확인.
라벨 선택기가 너무 제한적 라벨 필터 제거 또는 넓혀 일치하는 프로필 존재 확인.
라벨 선택기 문법 오류 라벨 선택기가 유효한 문법(예: {job="my-service"})을 사용하는지 확인. 지원 연산자는 쿼리 편집기 문서 참고.
Parca가 타겟을 스크랩하지 않음 Parca 구성에서 타겟이 스크랩되고 프로필이 수집되는지 확인.

쿼리 편집기 문제 (Query editor issues)

프로필 유형 드롭다운이 비어 있음:

증상: 프로필 유형 선택기에 옵션 없음. 버튼 텍스트가 Select a profile type이며 선택할 것이 없음.

원인 해결
Parca 연결 실패 데이터 소스 설정에서 Save & test로 연결 확인.
Parca에 스크랩된 데이터 없음 Parca가 타겟을 스크랩하고 프로필 데이터를 수집했는지 확인.
네트워크/인증 오류 브라우저 개발자 콘솔에서 profileTypes 리소스 엔드포인트로의 실패한 요청 확인.

"Both" 쿼리 유형이 없음:

증상: 쿼리 유형 옵션에 Metric과 Profile만 나타남. Both 옵션 사용 불가.

해결: 이는 의도된 동작이에요. Both 쿼리 유형은 Explore에서만 사용 가능해요. 대시보드 패널은 하나의 시각화 유형만 지원하므로 Grafana는 옵션을 Metric 또는 Profile로 제한해요. Explore에서 Both로 설정된 쿼리가 대시보드에서 사용되면 Grafana가 자동으로 Profile로 변경해요.

자동 완성 제안이 나타나지 않음:

증상: 라벨 선택기에 입력할 때 라벨 이름/값 제안이 나타나지 않음. 일부 라벨에서는 자동 완성이 작동하지만 다른 라벨에서는 안 됨.

원인 해결
라벨 이름이 로드되지 않음 쿼리 편집기를 연 후 잠시 대기. 자동 완성은 초기화 시 Parca에서 라벨 이름을 로드.
Parca 연결 실패 데이터 소스 연결 확인. 자동 완성은 labelNames와 labelValues 리소스 엔드포인트를 쿼리.
커서 위치 인식 안 됨 값 제안을 위해 중괄호 {} 안과 = 뒤에 커서 배치. 자동 완성은 {, ,, =, ~, ", 공백 같은 특정 문자에서 트리거.

템플릿 변수 문제 (Template variable issues)

변수가 쿼리에서 해석되지 않음:

증상: $variable 같은 변수 문법이 대체되지 않고 쿼리 결과에 리터럴로 나타남. 변수 사용 시 쿼리가 데이터 반환 안 함.

원인 해결
프로필 유형에서 변수 사용 템플릿 변수는 라벨 선택기 필드에서만 지원. 프로필 유형 드롭다운은 변수 보간을 지원하지 않음.
변수가 정의되지 않음 Dashboard options > Variables에 변수가 존재하고 유효한 값을 가지는지 확인.
잘못된 변수 문법 $variablename 또는 ${variablename} 사용. 변수 이름에 오타가 없는지 확인.

Parca로 변수 옵션을 채울 수 없음:

증상: Parca 데이터 소스로 쿼리 유형 변수를 만들 때 값이 반환되지 않음.

해결: Parca는 쿼리 유형 변수를 지원하지 않아요. Parca 데이터 소스로 변수 드롭다운을 동적으로 채울 수 없어요. Custom 변수(수동 정의 값), Text box 변수(자유 입력), 또는 쿼리 유형 변수에 다른 데이터 소스를 사용하세요. 지원되는 변수 유형과 예시는 Parca 템플릿 변수 문서 참고.

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

  • 구성 파일에서 Grafana 로그 레벨을 debug로 설정:
[log]
level = debug
  • /var/log/grafana/grafana.log(또는 구성된 로그 위치)에서 로그 검토.
  • 요청·응답 상세가 포함된 Parca 특정 항목 확인. 일반적인 로그 메시지:
    • "Failed to get profile types" — 프로필 유형 로딩 실패.
    • "Failed to get label names" — 라벨 자동 완성 데이터 로드 실패.
    • "Failed to process query" — Parca에 대한 쿼리가 오류 반환.
    • "Failed to unmarshall query" — 쿼리 JSON 파싱 실패.
  • 트러블슈팅 후 info로 재설정.

추가 도움 (Get additional help)

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

더 알아보기 (Learn more)