TestData 데이터 소스 트러블슈팅

TestData 데이터 소스를 사용할 때 겪을 수 있는 흔한 문제에 대한 해결책을 정리한 문서예요. TestData는 외부 의존성이 없는 내장 데이터 소스이므로 대부분의 문제는 시나리오 구성이나 데이터 포맷과 관련돼 있어요.

출처: Troubleshoot TestData data source issues

본문

쿼리 오류 (Query errors)

TestData 시나리오를 실행할 때 발생해요.

"No data" 또는 빈 패널:

증상: 패널이 "No data" 표시. 쿼리가 오류 없이 실행되지만 아무것도 반환하지 않음.

원인	해결
No Data Points 시나리오 선택	No Data Points 시나리오는 설계상 빈 결과를 반환. Random Walk 같은 다른 시나리오 선택.
Data Points Outside Range 선택	이 시나리오는 쿼리 시간 범위보다 1시간 전의 데이터 포인트를 반환. 시간 범위 확장 또는 다른 시나리오 선택.
CSV 시나리오의 빈 문자열 입력	CSV Metric Values와 CSV Content는 입력 데이터 필요. 콤마 구분 값 또는 CSV 콘텐츠 추가.
시간 범위에 데이터 없음	일부 시나리오는 쿼리 시간 범위에 상대적인 데이터를 생성. 대시보드 시간 범위 확장.

Conditional Error의 예상치 못한 오류:

증상: 쿼리가 서버 오류 또는 panic 메시지 반환. 쿼리 실행 시 즉시 오류 발생.

Conditional Error 시나리오는 String Input 필드가 비어 있으면 서버 panic을 트리거해요. 이는 오류 테스트를 위한 의도된 동작이에요.
오류 대신 데이터를 반환하려면 String Input 필드를 콤마 구분 값으로 채워요(예: 1,20,90,30,5,0).
오류 유형을 변경하려면 Error type 드롭다운에서 Server panic, Frontend exception, Frontend observable 중 선택.

Error with source가 오류 반환:

Error with source 시나리오는 의도적으로 오류를 반환해 Grafana가 다양한 오류 소스를 어떻게 처리하는지 테스트하게 해 줘요. 잘못된 구성이 아니에요. Plugin error source는 플러그인 자체에서 발생한 오류를, Downstream error source는 하류 서비스의 오류를 시뮬레이션해요. 이 시나리오로 알림 규칙, 오류 표시, 커스텀 패널의 오류 처리를 테스트할 수 있어요.

Slow Query가 멈춘 것처럼 보임:

증상: 쿼리가 오랜 시간 실행. 패널이 무한히 로딩 스피너 표시.

지연 기간을 제어하는 String Input 필드 확인(기본 5s).
더 짧은 기간으로 줄임(예: 1s 또는 500ms).
이 필드는 Go 기간 문법을 허용: 5s(초), 1m(분), 500ms(밀리초).

시각화에 대한 잘못된 데이터 유형:

증상: 패널이 "Data does not have a time field" 또는 유사한 유형 불일치 오류 표시. 시각화가 렌더링되지만 잘못 보임(그래프를 기대했는데 테이블 등).

시나리오를 시각화 유형과 매칭. 예: Logs 시나리오는 Logs 패널, Node Graph는 Node Graph 패널, Trace는 Traces 패널과 사용.
시계열 패널은 시계열 데이터를 생성하는 시나리오(Random Walk, Predictable Pulse, CSV Metric Values, Predictable CSV Wave) 필요.
테이블 패널은 Table Static, Random Walk Table, 또는 CSV File 사용.

Predictable Pulse 패턴이 기대와 안 맞음:

증상: on/off 패턴이 예상 시간과 어긋남. 값이 예상치 못한 간격으로 나타남.

Predictable Pulse는 epoch 기준 절대 시간으로 타임스탬프를 스텝 간격에 정렬해요. 즉 대시보드를 언제 로드하든 패턴이 같은 지점에서 시작돼요.
사이클 기간이 의도와 일치하는지 확인: 전체 사이클은 Step * (On Count + Off Count)초.
On Value와 Off Value가 올바르게 설정되었는지 확인. 기본값은 2와 1이지 1과 0이 아니에요.

CSV 및 데이터 입력 오류

사용자 제공 데이터를 받는 시나리오에서 발생해요.

CSV Content 또는 CSV Metric Values가 예상치 못한 결과 반환:

증상: 데이터가 기대와 안 맞음. 예상보다 데이터 포인트가 적음. 파싱 오류.

CSV 형식 확인: 첫 행에 헤더, 콤마 구분자, 숫자 값은 따옴표 없이.
CSV Metric Values의 경우 String Input 필드에 콤마 구분 숫자만 입력(예: 1,20,90,30,5,0).
null과 nan 특수 값은 Predictable CSV Wave 값에서 지원. 누락 데이터 포인트에 null, Not-a-Number 값에 nan 사용.
입력의 후행 콤마나 공백 확인.

Raw Frames JSON 파싱 오류:

증상: 유효하지 않은 JSON에 대한 오류 메시지. 패널 렌더링 실패.

JSON이 Grafana 데이터 프레임 형식과 일치하는지 검증.
편집기의 붙여넣기 도우미로 패널 JSON 또는 원시 쿼리 결과에서 데이터 가져오기.
각 필드 배열 내에서 필드 유형이 일관적인지 확인.

스트리밍 오류 (Streaming errors)

Streaming Client와 Grafana Live 시나리오에서 발생해요.

Streaming Client가 업데이트되지 않음:

증상: 패널이 초기 데이터를 보여 주지만 업데이트 안 됨. 시간이 지나도 새 데이터 포인트가 나타나지 않음.

Speed 필드가 합리적인 값(밀리초)인지 확인. 낮은 값이 더 빠른 업데이트를 만듦.
Fetch 유형의 경우 브라우저에서 URL에 접근 가능한지 확인.
브라우저 콘솔에서 WebSocket 또는 네트워크 오류 확인.

Grafana Live 채널에 데이터 없음:

증상: 채널 선택 후 패널이 비어 있음. 스트리밍 데이터가 나타나지 않음.

선택한 채널이 사용 가능한 옵션 중 하나와 일치하는지 확인: random-2s-stream, random-flakey-stream, random-labeled-stream, random-20Hz-stream.
Grafana 인스턴스에서 Grafana Live가 활성화되었는지 확인.
Grafana 서버 로그에서 Live 연결 오류 확인.

템플릿 변수 오류 (Template variable errors)

TestData를 대시보드 템플릿 변수와 사용할 때 발생해요.

변수 드롭다운이 비어 있음:

증상: 변수 드롭다운에 옵션 없음. 변수 편집기 미리보기가 0개 값 반환.

쿼리 문자열이 메트릭 트리에서 유효한 노드를 탐색하는지 확인. *로 모든 최상위 노드 반환.
점으로 구분된 경로 세그먼트가 트리 구조와 일치하는지 확인(예: A.*는 노드 A의 하위 반환). Z.* 같은 유효하지 않은 경로는 트리에 Z가 없으므로 아무것도 반환하지 않음.
변수 편집기에서 TestData 데이터 소스가 선택되었는지 확인.
테스트를 위해 변수 편집기 미리보기에서 Run query 클릭.

연결된 변수가 업데이트되지 않음:

증상: 의존 변수(예: $region.*)가 부모 변수 변경 시 새로고침되지 않음. 드롭다운이 이전 선택의 stale 값 표시.

변수 편집기에서 의존 변수의 Refresh 옵션을 On dashboard load 또는 On time range change로 설정.
쿼리가 올바른 부모 변수 문법을 사용하는지 확인(예: $region.*이지 region.*이 아님).

변수 값이 쿼리에서 보간되지 않음:

증상: 패널이 변수 값 대신 리터럴 문자열 $varname 표시. 변수 선택 변경 시 라벨이나 데이터가 안 바뀜.

올바른 변수 문법 확인: $varname 또는 ${varname}.
TestData는 Labels, Alias, Scenario, String Input, CSV Content, Raw Frame Content 필드에서만 변수를 보간해요. 다른 필드는 변수 대체를 지원하지 않아요.

알림 오류 (Alerting errors)

TestData를 Grafana Alerting과 함께 사용할 때 발생해요.

알림 규칙이 의외로 "no data" 표시:

증상: 패널에서는 시나리오가 동작하는데 알림 규칙 상태가 No Data. 알림이 firing이나 normal로 전환되지 않음.

백엔드 평가 시나리오를 사용하는지 확인. 브라우저 전용 시나리오(Streaming Client, Grafana Live, Grafana API, Steps, No Data Points)는 알림 엔진이 평가하면 빈 결과를 반환해요. Random Walk나 Predictable Pulse 같은 백엔드 시나리오 사용.
시나리오가 시계열 데이터를 반환하는지 확인. 로그(Logs), 트레이스(Trace), 그래프(Node Graph, Flame Graph), 테이블(Table Static)을 생성하는 시나리오는 알림 조건으로 사용할 수 없음.
필수인 시나리오(예: CSV Metric Values)에서 String Input 필드가 비어 있지 않은지 확인.

알림 규칙이 발화되지 않음:

증상: 알림 규칙이 Normal 상태로 유지. 패널에 데이터가 보이지만 알림 조건이 충족되지 않음.

Random Walk를 쓰면 값이 비결정적이라 임계값을 넘지 않을 수 있음. 임계값을 확실히 넘는 Predictable Pulse 또는 CSV Metric Values 사용.
Reduce 표현식이 올바르게 집계되는지 확인. 예: Last는 가장 최근 값을, Mean은 시리즈를 평균.
Threshold 표현식 확인. 알림 규칙 편집기에서 Preview로 평가된 값 확인.
평가 간격이 시나리오가 데이터 포인트를 생성할 만큼 충분히 긴지 확인. Step=60인 Predictable Pulse는 최소 60초 평가 창 필요.

템플릿 변수가 알림 규칙에서 해석되지 않음:

증상: 알림 규칙 오류가 해석되지 않은 변수 언급. 알림 쿼리가 $varname 문법 사용하지만 변수가 대체되지 않음.

Grafana는 대시보드 컨텍스트 없이 백엔드에서 알림 규칙을 평가해요. $varname 같은 템플릿 변수는 알림 평가 중에 해석되지 않아요. 시나리오 옵션에서 변수 참조를 고정 값으로 대체하세요.
자세한 내용은 알림 제한 사항 참고.

알림 평가 시간 초과:

증상: 알림 규칙이 Error 상태로 전환. 로그가 쿼리 평가 중 시간 초과 표시.

Slow Query 시나리오를 사용한다면 String Input 필드의 지연을 평가 간격보다 짧은 값으로 줄임.
다른 시나리오는 쿼리가 과도한 데이터 포인트를 생성하지 않는지 확인. 시간 범위를 줄이거나 스텝 간격 증가.

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

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

[log]
level = debug

/var/log/grafana/grafana.log(또는 구성된 로그 위치)에서 로그 검토.
testdata 또는 testdatasource를 포함하는 항목을 찾아 시나리오별 세부 사항 확인.
트러블슈팅 후 info로 재설정.

추가 도움 (Get additional help)

Grafana 커뮤니티 포럼에서 유사한 문제 확인.
Grafana GitHub 이슈에서 알려진 버그 검토.
이슈 보고 시 포함할 것: Grafana 버전, 선택한 시나리오와 그 구성, 오류 메시지(민감 정보 redact), 재현 단계.

TestData 데이터 소스 트러블슈팅