DataFusion SQL Telemetry에 대한 참조

Telemetry는 Apache DataFusion SQL을 사용하여 구조화된 이벤트 테이블을 쿼리합니다. Telemetry의 공개 레시피는 현재 게시되기 전에 Apache DataFusion 45.2.0으로 계획 및 실행됩니다. 이 참조는 고정된 테스트 도구 모음에서 실행되는 패턴을 설명합니다.

필드 이름과 유형은 여전히 ​​이벤트 계약에서 나옵니다. 애플리케이션이 실제로 사용하는 테이블, 단위, 상태, ID 규칙 및 시간 의미에 맞게 모든 예를 조정하세요.

제한된 읽기로 시작

운영 쿼리는 일반적으로 UTC 시간 필터로 시작하고 질문에 필요한 필드만 반환해야 합니다.

SELECT
  route_template,
  status_code,
  latency_ms,
  timestamp_utc
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY timestamp_utc DESC
LIMIT 100;

timestamp_utc는 서버 관리 쿼리 타임스탬프입니다. 소스 제공 timestamp 필드는 수집 중에 정규화되며 레시피에서 생성된 쿼리 열을 대체해서는 안 됩니다.

원시 행을 검사하는 동안 LIMIT를 사용합니다. 전체 내보내기를 위해서는 대화형 쿼리에서 모든 보호 장치를 제거하는 대신 비동기 쿼리 API를 사용하세요.

완전한 시간 버킷 생성

date_trunc는 추세에 맞는 안정적인 입자를 생성합니다.

SELECT
  date_trunc('hour', timestamp_utc) AS hour,
  COUNT(*) AS requests
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY date_trunc('hour', timestamp_utc)
ORDER BY hour;

가장 최근의 시간이나 날짜가 아직 채워져 있을 수 있습니다. 부분적인 볼륨으로 인해 결과가 오해될 경우 알림에서 해당 버킷을 제외합니다. 모든 비교에서 동일한 시간대, 버킷 크기 및 완전성 규칙을 사용하십시오.

조건부 개수 및 안전 요율

조건부 CASE 표현식은 그룹화된 동일한 행에서 여러 결과를 계산합니다.

SELECT
  route_template,
  COUNT(*) AS requests,
  SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END) AS errors,
  100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END)
    / NULLIF(COUNT(*), 0) AS error_rate_pct
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route_template
HAVING COUNT(*) >= 20
ORDER BY error_rate_pct DESC;

NULLIF는 분모가 0인 나눗셈을 보호합니다. 100.0를 곱하면 백분율 산술이 정수 나누기가 되는 것을 방지할 수 있습니다. HAVING 최소값은 조용한 그룹의 한 오류가 의미 있는 영향을 미치는 바쁜 경로보다 순위가 높은 것을 방지합니다.

백분위수 및 분포

효율적인 p95 추정을 위해 approx_percentile_cont(latency_ms, 0.95)를 사용하세요.

SELECT
  route_template,
  approx_percentile_cont(latency_ms, 0.50) AS p50_ms,
  approx_percentile_cont(latency_ms, 0.95) AS p95_ms,
  approx_percentile_cont(latency_ms, 0.99) AS p99_ms
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route_template;

p50을 p95 또는 p99와 비교하십시오. 배포 전반에 걸쳐 유사한 증가는 일반적으로 작업 흐름이 느려짐을 나타냅니다. 더 큰 꼬리 변화는 비정상적으로 느린 작업의 하위 집합을 가리킵니다. 백분위수는 추정치이므로 소수점 이하의 정밀도를 표시하지 마십시오.

히스토그램과 같은 결과를 얻으려면 CASE를 사용하여 명시적 버킷에 숫자 값을 할당하세요. "1000+"가 "250–499"보다 먼저 정렬되지 않도록 버킷 레이블과 순서 열을 별도로 유지하세요.

CTE는 정의를 검토 가능하게 만듭니다.

공통 테이블 표현식은 최종 집계에서 비즈니스 정의를 분리합니다.

WITH account_activity AS (
  SELECT
    account_id,
    MIN(CASE WHEN event_name = 'signup_completed' THEN timestamp_utc END)
      AS signed_up_at,
    MIN(CASE WHEN event_name = 'activation_completed' THEN timestamp_utc END)
      AS activated_at
  FROM product_events
  WHERE timestamp_utc >= now() - INTERVAL '30 days'
  GROUP BY account_id
)
SELECT
  COUNT(*) AS signed_up_accounts,
  SUM(CASE WHEN activated_at IS NOT NULL THEN 1 ELSE 0 END)
    AS activated_accounts
FROM account_activity
WHERE signed_up_at IS NOT NULL;

임시로 선택하여 중간 CTE를 검사합니다. 이는 중복된 ID, 예상치 못한 Null 또는 잘못된 행을 포함하는 마일스톤 정의를 찾아내는 가장 빠른 방법인 경우가 많습니다.

조인에는 명시적인 그레인이 필요합니다.

이벤트 테이블을 결합하기 전에 각 측면에 행 하나가 무엇을 나타내는지 명시합니다. 다대다 조인은 유효한 SQL을 반환하면서 개수를 늘릴 수 있습니다.

분석 단위인 경우 가입 전 계정, 요청, 작업, 웹훅 전달 또는 청구 기간당 하나의 행으로 사전 집계합니다. 상관 관계를 위해 생성된 안정적인 식별자를 사용하고 단지 고유해 보인다는 이유만으로 디스플레이 라벨에 결합하지 마십시오.

조인 후 다음을 비교하십시오.

• 전후의 행 개수
• 전후의 고유 식별자 수
• 양쪽에 일치하지 않는 행
• 결과가 알려진 경기에 대한 총계

창 기능

창 함수는 인접한 값을 비교하는 동안 행 또는 버킷 세부정보를 유지합니다.

WITH daily AS (
  SELECT
    date_trunc('day', timestamp_utc) AS day,
    COUNT(*) AS completed_jobs
  FROM job_events
  WHERE status = 'completed'
    AND timestamp_utc >= now() - INTERVAL '30 days'
  GROUP BY date_trunc('day', timestamp_utc)
)
SELECT
  day,
  completed_jobs,
  LAG(completed_jobs) OVER (ORDER BY day) AS previous_day_jobs,
  AVG(completed_jobs) OVER (
    ORDER BY day
    ROWS BETWEEN 6 PRECEDING AND CURRENT ROW
  ) AS rolling_7_bucket_average
FROM daily
ORDER BY day;

LAG는 이전 값을 노출합니다. 프레임이 있는 AVG는 롤링 기준선을 생성합니다. 앞의 행에는 불완전한 창이 있습니다. 알림을 생성하기 전에 표시할지, 억제할지 또는 레이블을 지정할지 결정하세요.

중첩된 필드 및 식별자

Telemetry는 점으로 구분된 필드 경로를 통해 중첩된 JSON를 노출합니다. 현재 테이블 스키마에서 점으로 구분된 경로를 인용해야 하는 경우 "data.tool.name"와 같이 큰따옴표로 묶인 식별자를 사용합니다. 중첩 필드 쿼리를 복사하기 전에 중첩 JSON 쿼리를 읽고 테이블 스키마를 검사하세요.

새 이벤트를 디자인할 때 snake_case 필드 이름을 사용하고 예약어나 모호한 단어를 사용하지 마세요. 기존 필드에 인용이 필요한 경우 동일한 개념에 대해 두 개의 철자를 생성하는 대신 일관되게 인용하십시오.

지원되는 패턴 및 고정된 제한

테스트된 레시피 모음은 SELECT, CTE, 조인, CASE, 공통 집계, date_trunc, 간격, 대략적인 백분위수, LAG, 프레임 창, NULLIF, COALESCE, 순서 지정, 그룹화 및 제한.

DataFusion는 PostgreSQL, MySQL, BigQuery 또는 Snowflake가 아닙니다. 유사해 보이는 함수는 다른 이름이나 서명을 가질 수 있습니다. Telemetry의 레시피 감사에서 사용되는 고정 플래너는 해당 시스템에서 발견된 모든 집계 수정자 또는 날짜 도우미를 허용하지 않습니다. 이 참조 및 테스트된 SQL 레시피 라이브러리에 설명된 구문을 선호하고 다른 방언의 예를 적용하기 전에 간단한 쿼리를 실행하세요.

쿼리 검토 체크리스트

쿼리를 저장하거나 알림에서 사용하기 전에:

1. 테이블, 열, 유형, 단위, UTC 시간 범위를 확인하세요.
2. 행위자 또는 워크플로 식별자를 정의하고 행 단위를 확인합니다.
3. 재시도, 중복, 지연 이벤트, Null 및 불완전한 버킷의 작동 방식을 결정합니다.
4. 분모 확인과 최소 의미 있는 거래량을 통해 비율을 보호하세요.
5. 중간 CTE 및 조인된 행 수를 검사합니다.
6. 합성 성공, 실패, 재시도, 중복 및 경계 사례를 테스트합니다.
7. 결과 옆에 정의, 소유자, 임계값 및 예상 응답을 기록합니다.

모든 레시피에는 스키마, 복사 가능한 SQL, 결정적 합성 출력, 시각화, 해석 메모, 극단적인 사례, 대시보드 제안 및 알림 지침이 포함됩니다. SQL 테스트 방법론을 읽은 후 API 신뢰성, 제품 분석, 데이터 품질 또는 인프라.