OpenTSDB 데이터 소스 트러블슈팅

OpenTSDB 데이터 소스 트러블슈팅

OpenTSDB 데이터 소스를 구성하거나 사용할 때 겪을 수 있는 흔한 문제에 대한 해결책을 정리한 문서예요. 연결 오류, 인증 오류, 쿼리 오류, 자동 완성, 템플릿 변수, 성능 문제를 다룹니다.

출처: Troubleshoot OpenTSDB data source issues

본문

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

연결 오류 (Connection errors)

Grafana가 OpenTSDB 서버에 연결할 수 없을 때 발생해요.

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

증상: Save & test 실패. 쿼리가 연결 오류 반환. 간헐적 시간 초과.

연결을 수동으로 테스트하려면:

curl http://<host>:4242/api/version

인증 오류 (Authentication errors)

자격 증명이 유효하지 않거나 잘못 구성되었을 때 발생해요.

"401 Unauthorized" 또는 "403 Forbidden":

증상: Save & test가 인증 오류로 실패. 쿼리가 인증 오류 반환.

• 데이터 소스 구성에서 기본 인증 자격 증명이 올바른지 확인.
• OpenTSDB 서버가 제공된 자격 증명을 수락하도록 구성되었는지 확인.
• 쿠키로 인증한다면 필수 쿠키가 Allowed cookies에 나열되어 있는지 확인.

쿼리 오류 (Query errors)

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

데이터가 반환되지 않음:

증상: 쿼리가 오류 없이 실행되지만 데이터 반환 없음. 패널이 "No data" 표시.

쿼리 시간 초과:

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

• 쿼리 시간 범위 줄임.
• 더 구체적인 태그 필터 추가로 데이터 볼륨 감소.
• 데이터 소스 구성에서 Timeout 설정 증가.
• 다운샘플링 활성화로 반환 데이터 포인트 수 감소.
• OpenTSDB 서버 성능과 HBase 상태 확인.

자동 완성 작동 안 함:

증상: 메트릭 이름, 태그 이름, 태그 값을 입력할 때 제안이 나타나지 않음. 드롭다운이 비어 있음.

• OpenTSDB /api/suggest 엔드포인트가 접근 가능한지 확인. 수동 테스트: curl http://<host>:4242/api/suggest?type=metrics.
• 메트릭/태그가 많다면 Lookup limit 설정 증가.
• Save & test 클릭으로 데이터 소스 연결이 작동하는지 확인.
• 메트릭이 OpenTSDB에 존재하는지 확인. suggest API는 데이터베이스에 쓰여진 메트릭만 반환.

템플릿 변수가 채워지지 않음:

증상: 템플릿 변수 드롭다운이 비어 있음. 값 미리보기에 결과 없음.

• OpenTSDB 구성에서 tsd.core.meta.enable_realtime_ts를 true로 설정해 실시간 메타데이터 추적 활성화.
• OpenTSDB 서버에서 tsdb uid metasync를 실행해 기존 메타데이터 동기화.
• 변수 쿼리 문법이 올바른지 확인. 올바른 문법은 템플릿 변수 문서 참고.
• 데이터 소스 연결이 작동하는지 확인.

성능 문제 (Performance issues)

느린 쿼리 또는 높은 리소스 사용과 관련된 문제예요.

느린 쿼리:

증상: 대시보드 로드가 오래 걸림. 작은 시간 범위에서도 쿼리가 느림.

• 쿼리 편집기에서 다운샘플링 활성화로 데이터 볼륨 감소.
• 반환되는 시계열을 제한하기 위해 더 구체적인 태그 필터 사용.
• 시간 범위 줄임.
• OpenTSDB와 HBase 성능 메트릭 확인.
• 메모리가 제한적이라면 OpenTSDB 힙 크기 증가 고려.

HBase 성능 문제:

OpenTSDB는 데이터 저장에 HBase를 의존해요. HBase의 성능 문제는 OpenTSDB 쿼리 성능에 직접 영향을 줘요.

• HBase region server 상태와 컴팩션 상태 모니터링.
• HBase region server에 충분한 힙 메모리 할당 확인.
• region 핫스팟 확인 및 필요한 경우 region 재분배.
• HBase 특정 문제는 OpenTSDB 트러블슈팅 가이드 참고.

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

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

[log]
level = debug

• /var/log/grafana/grafana.log(또는 구성된 로그 위치)에서 로그 검토.
• 요청·응답 상세가 포함된 OpenTSDB 특정 항목 확인.
• 트러블슈팅 후 info로 재설정.

추가 도움 (Get additional help)

• Grafana 커뮤니티 포럼에서 유사한 문제 확인.
• OpenTSDB GitHub 이슈에서 알려진 버그 검토.
• OpenTSDB 문서에서 서버별 지침 참고.
• Grafana Enterprise, Cloud Pro, Cloud Contracted 사용자라면 Grafana Support에 문의.

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

더 알아보기 (Learn more)

• OpenTSDB 데이터 소스
• OpenTSDB 데이터 소스 구성
• OpenTSDB 문서
• Grafana 커뮤니티 포럼
• OpenTSDB GitHub 이슈