Tempo 데이터 소스 트러블슈팅
Tempo 데이터 소스 트러블슈팅
Grafana에서 Tempo 데이터 소스를 구성하거나 사용할 때 겪을 수 있는 흔한 문제에 대한 해결책을 정리한 가이드예요. 연결, 인증, 쿼리, 스트리밍, Service Graph, 트레이스-로그/메트릭/프로파일 상관관계, 성능, PDC 문제를 다룹니다.
본문
가이드 범위 (Scope of this guide)
이 가이드는 Grafana를 Tempo에 연결하고 데이터 소스 기능을 사용하는 문제를 다룹니다. 다음 설정에 적용돼요.
- 자체 관리 Grafana + 자체 관리 Tempo — Grafana(OSS/Enterprise)와 Tempo를 모두 관리.
- Grafana Cloud + Cloud Traces — Grafana Cloud를 관리형 Tempo 백엔드와 사용. 일부 구성(스트리밍, metrics generator)은 자동 처리.
- Grafana Cloud + PDC를 통한 자체 관리 Tempo — Private data source connect로 자신의 Tempo 인스턴스에 연결.
설정별로 트러블슈팅 단계가 다르면 가이드가 명시해요. Grafana Cloud only 또는 self-managed Tempo 라벨이 붙은 섹션은 그 환경에만 적용돼요.
Tempo 자체 문제(데이터 소스 아님)는 Tempo 제품 문서를 참고하세요: 일반 트러블슈팅, 트레이스 찾을 수 없음, 429 too many requests, 쿼리 문제. Grafana Cloud 트레이싱 문제는 Grafana Cloud Traces 트러블슈팅과 Grafana Assistant 참고.
연결 오류 (Connection errors)
Tempo에 연결 실패:
오류 메시지: Failed to connect to Tempo 또는 dial tcp: connection refused
원인: Grafana가 Tempo 인스턴스에 도달할 수 없음. 대개 Tempo 프로세스가 실행 중이지 않거나, 데이터 소스 설정의 URL이 잘못되었거나, 네트워크 규칙이 연결을 차단하기 때문.
해결:
- Tempo 인스턴스가 실행 중이고 Grafana 서버에서 접근 가능한지 확인.
- 데이터 소스 구성의 URL이 올바른지 확인. 기본 Tempo HTTP 포트는
3200. 흔한 URL 실수:- 자체 관리 Tempo URL에
/api나/tempo같은 끝 경로 세그먼트 추가. 올바른 형식은 경로 없는http://<host>:3200./tempo접미사는 Grafana Cloud Traces URL에만 사용. - gRPC 포트(
9095)를 HTTP 포트(3200) 대신 사용. Tempo 데이터 소스 URL은 HTTP 엔드포인트여야 해요. Grafana는 같은 URL에서 스트리밍용 gRPC 연결을 파생해요.
- 자체 관리 Tempo URL에
- Grafana와 Tempo 사이 연결을 차단하는 방화벽 규칙이 없는지 확인.
- Grafana Cloud 사용자가 공개적으로 접근 불가한 자체 관리 Tempo에 연결한다면 PDC를 구성했는지 확인.
- 프로토콜(HTTP/HTTPS)이 Tempo 구성과 일치하는지 확인.
연결 시간 초과 (Connection timeout):
오류 메시지: Connection timed out 또는 context deadline exceeded
원인: 응답을 받기 전에 Tempo 연결이 시간 초과됨. 네트워크 지연이 높거나, Tempo가 과부하되거나, 중간 장치(로드 밸런서, 프록시)가 Tempo 응답 전에 연결을 종료할 때 발생.
해결: Grafana와 Tempo 사이 네트워크 지연 확인. Tempo가 과부하되지 않았는지 확인(Tempo mixin 대시보드로 리소스 포화/오류율 확인 가능). 데이터 소스 구성의 Additional settings 아래 Timeout 설정 증가. 네트워크 장치가 연결을 시간 초과시키는지 확인. 대형 트레이스 쿼리는 시간 범위를 줄이거나 더 구체적인 필터 추가.
TLS/SSL 연결 실패:
오류 메시지: TLS handshake failed 또는 x509: certificate signed by unknown authority
원인: Grafana의 TLS 설정과 Tempo가 지원·요구하는 것 사이 불일치. 예: Tempo가 Grafana 서버가 신뢰하지 않는 자체 서명 인증서를 제시하거나 인증서 hostname이 URL과 불일치.
해결: HTTPS 활성화 시 Tempo가 유효한 TLS 인증서가 있는지 확인. 인증서가 Grafana 서버가 신뢰하는지 확인. 자체 서명 인증서라면 데이터 소스 설정에서 TLS/SSL Auth Details 구성. 인증서의 CN/SAN이 URL의 hostname과 일치하는지 확인. Tempo TLS 암호화 설정은 Configure TLS communication 참고.
인증 오류 (Authentication errors)
인증 실패:
오류 메시지: 401 Unauthorized 또는 403 Forbidden
원인: 인증 자격 증명이 유효하지 않거나 사용자에게 Tempo 접근 권한이 없음. Save & test 선택 또는 쿼리 실행 시 나타남.
해결: 데이터 소스 설정에서 인증 자격 증명(사용자 이름/비밀번호 또는 API 키)이 올바른지 확인. 사용자/서비스 계정이 필요한 권한이 있는지 확인. 데이터 소스에서 선택한 인증 방법이 Tempo가 기대하는 것과 일치하는지 확인. Grafana Cloud라면 Cloud Access Policy 토큰에 traces:read 스코프가 있는지 확인. 자체 관리 Tempo라면 자격 증명이 Tempo server 블록 또는 리버스 프록시에 구성된 것과 일치하는지 확인.
Save and test가 404 반환:
오류 메시지: Save & test 선택 시 Tempo echo endpoint returned status 404
원인: Grafana 상태 점검이 서버에 도달하지만 api/echo 엔드포인트가 404를 반환. 가장 흔한 원인은 URL의 잘못된 경로 세그먼트(자체 관리 인스턴스의 /api나 /tempo)로 상태 점검 요청이 없는 경로로 이동하는 것. 404는 또한 Tempo 앞의 리버스 프록시가 예상치 못한 기본 인증 헤더를 포함한 요청을 거부할 때도 발생.
해결: URL에 끝 경로 세그먼트가 포함되지 않았는지 확인. 자체 관리 Tempo는 경로 없는 http://<host>:3200이어야 함. 리버스 프록시가 404를 반환하는지 확인(Tempo는 예상치 못한 auth 헤더를 무시하지만 프록시는 거부할 수 있음). Tempo가 인증을 요구하지 않으면 데이터 소스 설정에서 No authentication 선택. 자격 증명이 올바른 필드에 입력되었는지 확인. Grafana Cloud의 User 필드는 인스턴스 ID(로그인이 아님), Password는 Cloud Access Policy 토큰.
다중 테넌트 인증 문제:
오류 메시지: 다중 테넌트 Tempo 사용 시 Unauthorized
원인: 테넌트 ID(X-Scope-OrgID 헤더)가 누락되었거나 잘못됨. 이 헤더는 쓰기 경로(Alloy/OTel Collector 구성)와 읽기 경로(Grafana 데이터 소스 설정) 모두에 설정해 데이터를 올바른 테넌트로 라우팅해야 해요.
해결: Tempo 데이터 소스 설정에서 Authentication > HTTP Headers 아래 X-Scope-OrgID 헤더가 구성되었는지 확인. 쓰기 경로에서 Alloy/OTel Collector 구성에 같은 X-Scope-OrgID 헤더가 설정되어 트레이스가 올바른 테넌트로 수집되는지 확인. 인증된 사용자가 지정된 테넌트에 접근 권한이 있는지 확인. 교차 테넌트 쿼리 시 모든 지정 테넌트에 접근 가능한지 확인.
쿼리 오류 (Query errors)
트레이스를 찾지 못함:
오류 메시지: Trace not found 또는 trace ID not found
원인: 지정된 트레이스 ID가 Tempo에 없거나 구성된 보존 기간에서 벗어났음. 일반적인 이유:
- 샘플링: Alloy/OTel Collector 계측 파이프라인의 head/tail sampling이 Tempo에 도달하기 전에 트레이스를 버릴 수 있음(가장 흔한 원인).
- 보존: 트레이스는 Tempo 보존 구성에 설정된 기간 동안만 사용 가능.
- 수집 실패: 비율 제한, 오류, 잘못 구성된 파이프라인으로 트레이스가 성공적으로 수집되지 않았을 수 있음.
해결: 트레이스 ID가 올바르고 완전한지 확인. Alloy/OTel Collector의 샘플링 구성 확인(의도적으로 버려졌을 수 있음). 트레이스가 Tempo의 보존 기간 내인지 확인. 시간 범위 제한을 사용 중이라면 TraceID query 설정에서 시간 범위 확장. Enable Use time range in query 활성화와 time shift 값 조정으로 더 넓은 범위 검색. 트레이스가 성공적으로 수집되었는지 확인하려면 광범위한 쿼리 실행:
{ } | count() > 0
결과가 있으면 트레이스가 수집되고 있지만 샘플링으로 버려졌거나 기간이 지났을 수 있음.
TraceQL 문법 오류:
오류 메시지: parse error 또는 unexpected token
원인: TraceQL 쿼리에 문법 오류 포함.
해결: 쿼리가 TraceQL 문법을 따르는지 확인. 중괄호/괄호/따옴표 균형 확인. 속성 이름이 올바른 스코프로 올바르게 포맷되었는지 확인(점 표기법: span.http.status_code, resource.service.name). 문법이 익숙하지 않으면 Search 쿼리 빌더로 유효한 TraceQL 생성. 연산자(=, !=, =~, !~, >, <, >=, <=) 올바른 사용 확인.
쿼리가 결과를 반환하지 않음:
원인: 쿼리가 유효하지만 어떤 트레이스와도 일치하지 않음.
해결: 더 넓은 기간을 검색하도록 시간 범위 확장. 속성 이름과 값이 트레이스에 존재하는지 확인. 속성 이름이 대소문자 구분이므로 정확히 일치하는지 확인. Search 쿼리 빌더로 사용 가능한 속성/값 탐색. 더 넓은 쿼리로 시작해 점진적으로 필터 추가. Grafana Traces Drilldown(쿼리 없이 RED 메트릭으로 탐색) 시도. Tempo 검색은 비결정적이므로 동일한 쿼리가 다른 결과를 낼 수 있음(Tempo가 병렬 스캔 후 첫 번째 일치 트레이스를 반환). 알려진 트레이스 ID 쿼리로 트레이스가 Tempo에 수집되고 있는지 확인.
성공적인 연결 후 트레이스가 나타나지 않음:
원인: Save & test는 성공하지만 Explore 쿼리가 트레이스를 반환하지 않음. 데이터 소스 연결은 유효하지만 Tempo에 도달하는 트레이스 데이터가 없거나 쿼리가 수집된 데이터와 일치하지 않음.
해결: 애플리케이션이 계측되고 컬렉터(Alloy/OTel Collector)가 스팬을 Tempo로 전달하는지 확인. 컬렉터 로그에서 전송 오류, 거부된 스팬, 드랍 확인. 쿼리 시간 범위가 트레이스 생성 기간을 포함하는지 확인. 다중 테넌트 설정에서 X-Scope-OrgID 헤더가 쓰기·읽기 경로에서 동일한지 확인(불일치 시 한 테넌트로 수집, 다른 테넌트로 쿼리). 짧고 최근 시간 범위로 {} 같은 광범위 쿼리 시도 — 결과가 있으면 원래 쿼리 필터가 너무 좁은 것.
쿼리 시간 초과:
오류 메시지: context deadline exceeded 또는 query timeout
원인: 쿼리 실행이 너무 오래 걸림. 트레이스 검색은 선택한 시간 범위 전반의 원시 트레이스 데이터를 스캔하므로, 긴 기간의 광범위 쿼리는 시간 초과 한도를 초과할 수 있음.
해결: 스캔 데이터 양을 제한하도록 시간 범위 줄임. 검색 범위를 좁히는 더 구체적인 필터 추가. 가능하면 쿼리에 인덱스 속성 사용(빠른 조회). 자체 관리 Tempo는 필요한 경우 Tempo 서버 구성에서 쿼리 시간 초과 증가. 개별 트레이스 대신 집계 데이터(rate, count, duration)가 필요하면 TraceQL 메트릭 쿼리({ } | rate())나 metrics generator의 사전 계산 메트릭 사용(집계 워크로드 최적화).
TraceQL 메트릭 쿼리 실패:
오류 메시지: localblocks processor not found 또는 metrics-generator not configured
원인: TraceQL 메트릭 쿼리({ } | rate(), { } | count_over_time())는 Tempo metrics-generator 구성에 local-blocks 프로세서가 활성화되어 있어야 해요. 이 프로세서는 service-graphs와 span-metrics 프로세서와 별개이며 독립적으로 활성화해야 해요.
해결: 자체 관리 Tempo의 overrides 구성에서 local-blocks 프로세서 활성화.
Standard: overrides.metrics_generator_processors: ["local-blocks"]
Newer versions and Helm: overrides.defaults.metrics_generator.processors: [local-blocks]
Grafana Cloud는 local-blocks 프로세서가 기본 활성화돼 있어요. 여전히 오류가 보이면 Grafana Support에 문의. metrics generator가 실행 중이고 건강한지 Tempo metrics-generator 로그 확인.
스트리밍 문제 (Streaming issues)
스트리밍은 TraceQL 쿼리 결과를 사용 가능해지면 표시해요. Grafana Cloud 사용자에게는 기본 제공돼요. 자체 관리 Tempo는 검색 스트리밍에 Tempo v2.2+, 메트릭 스트리밍에 v2.7+ 필요하며, 둘 다 Tempo 구성에 stream_over_http_enabled: true가 필요해요.
스트리밍 안 됨: 결과가 점진적으로 나타나지 않고 전체 쿼리 완료 후에만 표시. 자체 관리 Tempo는 필요 버전(v2.2+/v2.7+)과 stream_over_http_enabled: true를 확인. Tempo 데이터 소스 설정에서 스트리밍 활성화 확인(Search·Metrics 쿼리 토글은 독립적). gRPC/HTTP2를 지원하지 않는 로드 밸런서/프록시 뒤라면 스트리밍 작동 안 할 수 있음 — 비활성화하고 표준 HTTP 쿼리 사용. PDC로 Tempo에 도달한다면 PDC 터널이 실행 중이고 Tempo가 PDC 에이전트에서 도달 가능한지 확인(PDC 연결 문제가 스트리밍 시간 초과로 나타날 수 있음).
gRPC 전송 보안 오류:
오류 메시지: rpc error: code = Unavailable desc = credentials require transport level security
원인: Grafana가 비보안(비TLS) 연결로 gRPC를 사용하려 함. 스트리밍은 gRPC를 사용하며 Tempo 구성에 따라 TLS가 필요할 수 있음.
해결: Grafana와 Tempo 사이 TLS 구성. TLS가 불가능하면 Tempo 데이터 소스 설정에서 스트리밍 비활성화하고 표준 HTTP 쿼리 사용.
부분 결과 또는 스트리밍 오류: 스트리밍 연결이 모든 결과 전달 전 중단됨. 브라우저와 Grafana 사이 네트워크 안정성 확인. 프록시/로드 밸런서가 장기 연결을 종료하지 않는지 확인. 문제가 지속되면 스트리밍 비활성화 후 표준 쿼리 사용. Tempo 서버 로그에서 스트리밍 관련 오류 확인.
Service Graph 문제
Service Graph은 서비스 의존성을 시각화하고 연결 전반의 RED 메트릭을 강조해요. 연결된 Prometheus 데이터 소스와 Tempo metrics generator/Grafana Alloy가 생성한 service graph 메트릭이 필요해요.
Service graph이 표시되지 않음: Tempo 데이터 소스 Additional settings의 Service Graph 설정에 Prometheus 데이터 소스가 연결되어 있는지 확인. 자체 관리 Tempo는 metrics generator가 service graph 메트릭 생성하도록 구성되었는지 확인. 다음 service graph 메트릭이 Prometheus에 존재하는지 확인: traces_service_graph_request_total, traces_service_graph_request_failed_total, traces_service_graph_request_server_seconds_sum. Grafana Alloy 또는 Tempo metrics generator가 이 메트릭을 생성하도록 구성되었는지 확인(Service Graph view 테이블을 위한 span metrics traces_spanmetrics_*와 다름). 메트릭 존재 확인:
{__name__=~"traces_service_graph_request.*"}
Prometheus 데이터 소스 연결이 작동하는지 확인.
Service Graph view 테이블이 비어 있음: 노드 그래프는 정상 렌더링되지만 옆의 RED 메트릭 테이블이 데이터 없음. 테이블은 노드 그래프와 다른 메트릭 집합을 사용하며, Grafana 프론트엔드가 traces_spanmetrics_calls_total과 traces_spanmetrics_latency_bucket을 쿼리해요. 링크된 Prometheus에 이 메트릭이 있는지 확인. 새 Tempo 버전은 traces_spanmetrics_latency_bucket 대신 traces_spanmetrics_duration_seconds_bucket을 생성할 수 있으므로, 새 메트릭 이름만 있다면 Grafana 프론트엔드가 지원할 때까지 duration 열은 데이터 없음. span metrics 생성을 Tempo/Alloy 구성에서 활성화했는지 확인.
높은 카디널리티 경고: service graph/span metrics 쿼리가 높은 카디널리티 경고나 느린 쿼리를 생성. 서비스 그래프와 span 메트릭의 라벨 카디널리티 검토(고유 Pod 이름·요청 ID 같은 높은 카디널리티 라벨이 많은 시계열 생성).
Service graph이 불완전한 데이터 표시: 일부 서비스·연결이 그래프에서 누락. 모든 서비스가 계측되고 스팬을 보내는지 확인. 스팬 이름과 서비스 이름이 일관적인지 확인. 시간 범위가 모든 예상 서비스의 데이터를 포함하는지 확인.
트레이스-로그/메트릭/프로파일 문제
Trace to logs 링크가 안 나타남: Trace to logs 설정에 Loki 또는 다른 로그 데이터 소스가 구성되었는지 확인. 구성된 태그가 스팬에 존재하는지 확인. 최소 하나의 매핑된 태그에 스팬에서 비어 있지 않은 값이 있는지 확인. 커스텀 쿼리 사용 시 대상 데이터 소스에 유효한 문법인지 확인. 커스텀 쿼리 사용 시 Filter by trace ID 또는 Filter by span ID가 활성화되지 않았는지 확인. Loki 파생 필드로 Filter by trace ID를 사용한다면 파생 필드 정규식이 로그에서 사용한 트레이스 ID 필드 이름과 일치하는지 확인(라이브러리별 traceID, trace_id, traceId 다름).
Loki 로그 라인에 트레이스 링크 없음: Loki 데이터 소스의 Additional settings > Derived fields에 파생 필드가 구성되었는지 확인. 파생 필드 정규식이 로그의 트레이스 ID 형식과 일치하는지 확인. Internal link 토글이 활성화되고 올바른 Tempo 데이터 소스를 가리키는지 확인. 서비스별 트레이스 ID 필드 이름이 다르면 형식별 별도 파생 필드 항목 필요.
Trace to metrics 링크 안 나타남: Trace to metrics 설정에 Prometheus 메트릭 데이터 소스가 구성되었는지 확인. 구성된 태그가 스팬에 존재하는지 확인. 커스텀 쿼리가 유효한 PromQL인지 확인. $__tags 변수가 커스텀 쿼리에 올바르게 배치되었는지 확인.
Trace to profiles 링크 안 나타남: Trace to profiles 설정에 Grafana Pyroscope 데이터 소스가 구성되었는지 확인. 구성된 태그가 스팬에 존재하는지 확인. 구성된 프로파일 유형이 Pyroscope 데이터와 일치하는지 확인(예: process_cpu:cpu:nanoseconds:cpu:nanoseconds). Span start time shift와 Span end time shift 값 좁히기 — 프로파일은 간격으로 샘플링되므로 스팬 주변의 좁은 시간 창이 넓은 것보다 프로파일 데이터와 일치할 가능성이 높음.
링크가 나타나지만 데이터 반환 없음: 생성된 쿼리가 대상 데이터 소스의 어떤 데이터와도 일치하지 않음. Span start/end time shift 조정해 시간 범위 넓힘. 로그/메트릭 라벨이 스팬 속성과 일치하는지 확인. 태그 매핑이 데이터 소스 간 속성 이름을 올바르게 변환하는지 확인(스팬 속성은 점 예: service.name, Loki 라벨은 밑줄 예: service_name). pod 같은 태그가 Loki 구조적 메타데이터로 저장되면 자동 생성된 스트림 셀렉터 {pod="..."}가 결과 없음 — 커스텀 쿼리 활성화하고 태그를 파이프라인 필터로 이동. 대상 데이터 소스의 Explore에서 생성 쿼리를 직접 실행해 확인. Query Inspector로 생성된 쿼리 확인.
성능 문제 (Performance issues)
느린 트레이스 쿼리: 대시보드/Explore 시간 범위 줄임. 검색 범위를 좁히는 더 구체적인 필터 추가. 가능하면 TraceQL 쿼리에 인덱스 속성 사용. 스트리밍 활성화로 결과를 즉시 확인. 쿼리 최적화에 도움을 주는 Search 쿼리 빌더 고려.
쿼리 중 높은 메모리 사용: 대형 트레이스·결과 집합이 과도한 메모리를 소비. 쿼리 옵션의 Limit 설정을 줄여 반환 트레이스 수 감소. Span Limit 설정을 줄여 트레이스당 반환 스팬 수 감소. 결과 집합 크기를 줄이는 필터 추가. 매우 큰 시간 범위 쿼리 회피.
기타 흔한 문제
Node graph가 표시되지 않음: Tempo 데이터 소스 Additional settings에서 Node graph가 활성화되었는지 확인. 트레이스가 부모-자식 관계의 여러 스팬을 포함하는지 확인. 스팬은 traceID와 spanID를, 루트가 아닌 스팬은 parentSpanID를 포함해야 계층 구조가 성립돼요. 이 식별자가 없으면 계측 수준에서 트레이스 데이터가 불완전해 그래프를 렌더링할 수 없음.
자동 완성이 작동하지 않음: TraceQL 편집기가 속성/값 제안을 표시하지 않음. 자동 완성은 Tempo가 태그를 열거해야 하며, 지원 스토리지 백엔드(vParquet 이상)가 필요해요. 자체 관리 Tempo의 스토리지 백엔드가 태그 검색을 지원하는지 확인(vParquet 이상 필요). 데이터 소스 설정의 Tags time range가 최근 트레이스 데이터가 있는 기간을 포함하는지 확인. 고유 속성이 많으면 Tag limit 증가. Save & test로 연결 확인.
재시작 후 데이터 소스 설정이 사라짐: Grafana UI에서 구성(예: trace-to-logs 링크, service graph, span time shift)했지만 Grafana 재시작 후 사라짐. 이는 데이터 소스가 YAML 구성 파일, Helm 차트, Terraform으로 프로비저닝되었을 때 발생. 프로비저닝된 데이터 소스는 UI에서 읽기 전용이며, UI 변경은 저장되지 않고 다음 재시작 시 조용히 되돌아가요. 데이터 소스가 프로비저닝됐는지 확인하려면 설정 폼이 읽기 전용이고 버튼이 Save & test 대신 Test인지 확인. 영구 변경하려면 프로비저닝 YAML 파일을 편집하고 Grafana 재시작(또는 프로비저닝 시스템 재로드 대기). Grafana Cloud는 프로비저닝된 데이터 소스를 복제해 UI 변경이 유지되는 편집 가능한 사본을 만들 수 있어요.
TraceQL 알림 사용 불가: Grafana Alerting 규칙 빌더에서 Tempo 데이터 소스를 선택할 수 있지만, 표준 TraceQL 검색 쿼리는 트레이스 데이터(스팬·트레이스 ID)를 반환하지 수치 시계열을 반환하지 않음. 알림 규칙은 임계값 평가에 숫자 데이터가 필요하므로 트레이스 검색 쿼리는 사용 가능한 알림 조건을 만들지 못해요. TraceQL 메트릭 쿼리({ } | rate(), { status = error } | count_over_time())는 수치 시계열을 반환하고 알림 임계값을 구동할 수 있지만, TraceQL 알림은 실험적 tempoAlerting feature flag가 필요하며 기본 비활성화예요. 이 플래그는 실험적이므로 프로덕션 알림에는 Tempo metrics generator로 트레이스에서 Prometheus 메트릭을 생성한 뒤 그 메트릭이 들어간 Prometheus 데이터 소스에 알림 규칙을 만드는 Prometheus 기반 접근을 고려하세요.
여러 Tempo 인스턴스 간 전환: 여러 Tempo 데이터 소스가 구성되어 있지만 Explore/대시보드에 동적으로 전환하는 내장 UI 드롭다운이 없음. 대시보드에서는 tempo 유형으로 필터링된 데이터 소스 템플릿 변수를 만들어 뷰어가 대시보드를 편집하지 않고도 Tempo 인스턴스를 전환할 수 있게 해요. Explore에서는 상단 바의 데이터 소스 선택기로 전환. 단일 Tempo 인스턴스의 다중 테넌트 설정은 별도 데이터 소스 대신 X-Scope-OrgID 헤더 사용 고려.
PDC 문제 (Grafana Cloud만 해당)
PDC 에이전트가 연결되지 않음: 오류 메시지 No healthy PDC agents available 또는 Private data source connect agent not connected. 원인: 사설 네트워크에 설치된 PDC 에이전트가 실행되지 않거나 Grafana Cloud에 연결할 수 없음. 해결: PDC 에이전트가 실행 중인지, 로그에서 연결 오류가 없는지 확인. Grafana Cloud 엔드포인트로 아웃바운드 접근이 있는지 확인. 올바른 토큰을 사용하는지 확인. 방화벽이 아웃바운드 HTTPS(443)를 허용하는지 확인. 멈춘 것 같으면 에이전트 재시작.
PDC를 통한 연결 실패: 오류 메시지 Failed to connect through private data source 또는 Connection refused via PDC. 원인: PDC 에이전트가 Grafana Cloud에 연결되었지만 사설 네트워크의 Tempo 인스턴스에 도달할 수 없음. 해결: Tempo URL이 올바르고 PDC 에이전트가 실행되는 머신에서 접근 가능한지 확인. 에이전트가 Tempo hostname을 해석할 수 있는지(DNS) 확인. 에이전트에서 Tempo로 연결을 차단하는 방화벽이 없는지 확인. Tempo 포트(기본 3200)가 열려 있는지 확인. PDC 에이전트 호스트에서 curl/telnet으로 연결 테스트.
PDC 시간 초과 오류: PDC 터널을 통한 쿼리가 시간 초과. PDC 에이전트와 Tempo 사이 네트워크 지연 확인. 에이전트 호스트에 충분한 리소스(CPU, 메모리, 대역폭)가 있는지 확인. 에이전트와 Tempo 사이 장치가 장기 연결을 끊지 않는지 확인. 대형 쿼리는 시간 범위 줄이거나 필터 추가. 여러 데이터 소스가 같은 PDC 에이전트를 공유해 리소스 경쟁이 있을 수 있음.
PDC 인증 불일치: PDC 사용 시 Unauthorized 또는 403 Forbidden. 데이터 소스 인증 자격 증명이 올바르게 구성되었는지 확인. Tempo가 구성된 인증 방법을 수락하는지 확인. 필요한 헤더(다중 테넌트 Tempo의 X-Scope-OrgID)가 PDC를 통해 올바르게 전달되는지 확인. PDC 외부에서 자격 증명이 작동하는지 에이전트 호스트에서 직접 연결 테스트.
추가 도움 (Get additional help)
- Grafana Cloud 사용자는 Grafana Assistant로 대화형 트레이스 문제 조사.
- Alloy로 트레이스를 보내는 Grafana Cloud 사용자는 수집 측 문제에 Alloy 트러블슈팅 참고.
- Grafana 커뮤니티 포럼 또는 Grafana Community Slack에서 질문.
- Grafana GitHub 이슈와 Tempo GitHub 이슈 검토.
- Grafana에서 debug 로깅 활성화로 자세한 오류 정보 수집.
- Tempo 서버 로그에서 추가 오류 세부 정보 확인.
- Enterprise, Cloud Pro, Cloud Contracted 사용자라면 Grafana Support에 문의.
이슈 보고 시 Grafana 버전, Tempo 버전, 오류 메시지(민감 정보 redact), 재현 단계, TraceQL 쿼리 예시, 관련 구성 설정을 포함하세요.