코딩 에이전트와 함께 이 문서를 사용하세요.

Claude Code, Codex, Cursor 또는 다른 코딩 에이전트에 대한 집중 프롬프트 팩을 연 다음 여기에서 다루는 워크플로에 맞게 조정하세요.

지연 시간 및 분포에 대한 SQL 백분위수

평균은 분포를 하나의 숫자로 압축합니다. 이는 총계 및 광범위한 추세에 유용하지만 사고 중에 중요한 느린 경험을 숨길 수 있습니다. 백분위수는 다른 질문에 답합니다. p95는 관측치의 대략 95%가 해당하는 값 또는 그 이하입니다.

분포의 여러 점 쿼리

Telemetry는 Apache DataFusion SQL을 사용합니다. 실제 백분위수 추정에는 approx_percentile_cont를 사용하세요.

SELECT
  route_template,
  COUNT(*) AS requests,
  approx_percentile_cont(duration_ms, 0.50) AS p50_ms,
  approx_percentile_cont(duration_ms, 0.95) AS p95_ms,
  approx_percentile_cont(duration_ms, 0.99) AS p99_ms,
  MAX(duration_ms) AS maximum_ms
FROM api_request_events
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route_template
HAVING COUNT(*) >= 100
ORDER BY p95_ms DESC;

결과에 요청 수를 유지합니다. 작은 그룹의 백분위수는 불안정하며 그룹에 소수의 관측값만 포함된 경우 p99는 의미가 없습니다. 또한 대략적인 결과를 인위적인 소수점 이하 정밀도로 제시해서는 안 됩니다.

순위뿐만 아니라 형태도 해석

p50, p95 및 p99가 모두 함께 상승하면 전체 워크플로가 변경되었을 수 있습니다. p99가 증가하는 동안 p50이 안정적으로 유지되면 요청의 하위 집합에 꼬리 지연 시간이 발생하는 것입니다. 최대값은 조사에 유용하지만 하나의 이상값이 정상적인 성능을 정의해서는 안 됩니다.

작업을 변경할 수 있는 차원(경로 템플릿, 종속성, 릴리스, 지역 또는 제한된 작업 이름)별로만 그룹화합니다. 원시 URL과 무제한 쿼리 텍스트는 비교하기 어렵고 민감한 값을 노출할 수 있는 높은 카디널리티 그룹을 생성합니다.

백분위수는 백분율이 아닙니다. p95 대기 시간이 800밀리초라고 해서 요청의 95%가 느리다는 의미는 아닙니다. 이는 해당 값 이하로 약 95%가 완료되었음을 의미합니다. 숫자를 검토된 목표 및 명시적인 단위와 연결합니다.

테스트된 예시에는 API 지연 시간 레시피, 종속성 지연 시간 레시피 또는 큐 대기 레시피를 사용하세요. 분포 시각화 가이드는 히스토그램이 3백분위수 지점보다 더 많은 것을 나타내는 경우를 설명합니다.

소유권 및 기술 참조

이 설명은 Telemetry 편집팀의 소유입니다. 제품 팀은 동작, 예시, 경계를 검토합니다.

편집 기준 검토

아파치 DataFusion SQL 참조