Pyroscope 데이터 소스 문제 해결

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

이 문서는 Pyroscope 데이터 소스를 구성하거나 사용할 때 겪을 수 있는 일반적인 문제에 대한 해결책을 제공해요. 연결·구성, 인증, 쿼리, 플레임 그래프, 템플릿 변수, Profiles Drilldown, Trace to profiles, 성능 오류로 나눠 설명합니다.

출처: 문서

본문

연결 및 구성 오류

"Data source is not working" 또는 연결 실패

URL 형식 문제 / "Connection refused" 또는 타임아웃 / SSL/TLS 오류 / 프라이빗 연결 또는 리버스 프록시 문제

URL 형식이 올바른지, 포트·프로토콜이 맞는지, 프록시 설정과 네트워크 경로를 확인하세요.

인증 오류

"Authentication failed" 또는 "Unauthorized"

Grafana Cloud 액세스 정책 및 토큰 문제

• 원인: Grafana Cloud Profiles는 사용자 비밀번호가 아니라 액세스 정책 토큰으로 인증해요. 토큰은 profiles:read 스코프를 포함하고 올바른 스택을 대상으로 하는 액세스 정책에 속해야 해요. 잘못된 스코프의 토큰이나 다른 스택용으로 만든 토큰은 인증에 실패하거나 다른 테넌트의 데이터를 반환해요. 토큰과 연결 URL은 스택별로 다르며 마이그레이션 중에 이전되지 않아요.
• 해결: 올바른 스코프와 스택을 대상으로 하는 새 토큰을 만들고 연결 URL을 확인하세요.

쿼리 오류

"No data" 또는 빈 결과

참고: 데이터 소스 연결 테스트는 성공하는데 어떤 쿼리에 대해서도 프로파일이 없다면, 보통 데이터 소스가 아니라 수집(ingestion) 쪽 문제예요. 데이터 소스는 Pyroscope에서 프로파일을 읽기만 할 뿐 수집·전송하지 않아요. Grafana Alloy나 OpenTelemetry Collector 같은 애플리케이션·SDK·수집기가 프로파일을 Pyroscope 백엔드로 보내는지 확인하세요.

"Profile type not found" 또는 빈 프로파일 유형 선택기 / 라벨 이름·값이 로드되지 않음 / 쿼리 구문 오류

프로파일 유형이 데이터 소스에 있는지, 라벨 구문을 확인하고 유효한 쿼리 예시를 참고하세요:

{service_name="my-app"}
{service_name="my-app", env="production"}
{service_name=~"my-app.*"}

긴 시간 범위 쿼리가 최근 데이터만 반환

오래된 데이터가 보존됨에도 쿼리가 최근 며칠 데이터만 반환하면, 쿼리 시간 범위가 서버 측 쿼리 한도를 초과하는 경우가 많아요. Grafana Cloud Profiles에서 가장 흔히 보고돼요. "쿼리 시간 범위 및 보존 한도"를 참고하세요.

플레임 그래프 문제

• 플레임 그래프가 렌더링되지 않음: 데이터와 프로파일 유형을 확인하세요.
• 큰 시간 범위에서 타임아웃/로드 실패: 큰 시간 범위의 플레임 그래프 렌더링은 Pyroscope 백엔드가 많은 프로파일을 병합해야 해 쿼리 시간과 메모리가 증가해요. 크거나 고카디널리티 범위는 결과가 반환되기 전에 요청 타임아웃을 초과할 수 있어요. 시간 범위를 줄이거나 프로파일 밀도를 낮추세요.
• 플레임 그래프가 상세 없이 집계 데이터만 표시: 시간 범위를 확대해 더 높은 세분도를 얻으세요.
• 플레임 그래프와 상호작용 불가: 프로파일 유형과 라벨 선택을 확인하세요.

템플릿 변수 오류

• 변수가 값을 반환하지 않음: 쿼리 유형·프로파일 유형·라벨 설정을 확인하세요.
• 변수가 예상대로 필터링하지 않음: =~ 연산자 사용과 변수 형식을 확인하세요.

Profiles Drilldown 문제

• Profiles Drilldown 사용 불가: Grafana 버전과 플러그인 설치를 확인하세요.
• 서비스/프로파일이 나타나지 않음: 데이터 소스와 데이터 수집을 확인하세요.

Trace to profiles 문제

Trace to profiles는 데이터 소스에서 가장 구성에 민감한 기능이에요. 대부분의 문제는 데이터 소스 오설정보다 충족되지 않은 사전 요구 사항에서 옵니다. 모든 전제 조건(데이터 소스 구성, pyroscope.profile.id 속성, 언어 SDK 계측)을 확인하세요.

• 스팬 프로파일이 나타나지 않음: pyroscope.profile.id 속성과 브리지 구성을 확인하세요.
• 프로파일이 트레이스 스팬과 일치하지 않음: 태그·시간 범위가 일치하는지 확인하세요.
• eBPF 기반 수집에서 스팬 프로파일 사용 불가: 스팬 프로파일링은 프로파일링 샘플을 활성 트레이스 스팬과 연관시키는데, 이는 언어 SDK와 OpenTelemetry 스팬-프로파일링 브리지가 필요해요. eBPF 기반 수집은 샘플을 개별 스팬과 연관시킬 수 없으므로 스팬 프로파일을 생성하지 않아요.
• 스팬 ID가 아닌 스팬 이름/트레이스 ID로 스팬 프로파일 필터링: 스팬-프로파일링 브리지는 profiling 샘플에 span_name과 trace_id를 라벨링해요. SDK에 따라 프로파일링 컨텍스트가 트레이스의 루트 스팬에만 붙고 자식 스팬이 상속할 수 있어요. span_id는 고카디널리티라 신뢰할 수 있는 상관 라벨이 아니에요.
• .NET 프로파일러가 OpenTelemetry 자동 계측과 충돌: .NET CLR은 프로세스에 한 번에 프로파일러 하나만 붙일 수 있어요. Pyroscope .NET 프로파일러와 OpenTelemetry 자동 계측은 각각 별도의 CLR 프로파일러에 의존하므로 충돌해요.
• 로그를 프로파일과 상관: Grafana는 Trace to profiles를 지원하지만 로그-프로파일 직접 상관은 없어요.

성능 문제

• 느린 쿼리 또는 타임아웃: 시간 범위와 라벨 선택을 좁히세요.
• 브라우저의 높은 메모리 사용: Max Nodes를 낮추거나 시간 범위를 줄이세요.

Grafana Cloud 관련 문제

쿼리 시간 범위 및 보존 한도

• 원인: Pyroscope는 데이터 보존 기간과 분리된(종종 더 짧은) 서버 측 쿼리 한도를 적용해요. 이 한도는 Grafana 데이터 소스가 아니라 Pyroscope 쿼리 프론트엔드가 적용하므로 데이터 소스가 변경·재정의할 수 없어요.

보존이 보통 쿼리 창보다 길기 때문에 프로파일이 보존되지만 조회할 수 없는 경우가 있어요. 예를 들어 Grafana Cloud Profiles는 무료 요금제 14일, 유료 요금제 30일 보존하지만 기본 쿼리 창은 7일이에요.

참고: 표시된 기본값은 Pyroscope OSS 기본값이에요. Grafana Cloud와 자체 관리 배포는 다른 값을 구성할 수 있어요.

디버그 로깅 활성화

문제 해결을 위해 상세 오류 정보를 캡처하려면 Grafana 로그 레벨을 DEBUG로 설정하세요.

더 알아보기 (Learn more)

• Pyroscope 데이터 소스 구성
• Pyroscope 쿼리 에디터
• 클라이언트가 프로파일 보내도록 구성
• Trace to profiles 구성
• Pyroscope 템플릿 변수