옵저버빌리티 및 이벤트 분석을 위한 SQL

SQL 옵저버빌리티은 가시적이고 검토 가능한 쿼리를 통해 구조화된 이벤트의 운영 및 제품 질문에 답하는 것을 의미합니다. 제한되지 않은 메시지를 검색하고 모든 생성자가 동일한 방식으로 형식을 지정하기를 바라는 대신 route, status_code, latency_ms, account_id, release 및 outcome와 같은 유용한 필드를 정의한 다음 해당 열을 직접 집계합니다.

이로 인해 텍스트 로그, 메트릭 또는 추적이 더 이상 사용되지 않게 되는 것은 아닙니다. 이는 소프트웨어 팀에 신뢰성, 제품 동작, 비용 및 고객 영향에 대한 질문에 대한 관계형 분석 계층을 제공합니다.

짧은 버전

유용한 SQL 옵저버빌리티 워크플로는 다섯 부분으로 구성됩니다.

1. 의미 있는 작업을 위해 하나의 터미널 이벤트를 기록합니다.
2. 작고 안정적인 차원, 측정값 및 상관 관계 식별자 집합을 유지합니다.
3. 신뢰할 수 있는 타임스탬프를 사용하여 유형이 지정된 테이블에 이벤트를 저장합니다.
4. 읽기 전용 SQL을 사용하여 행을 필터링, 그룹화, 조인 및 비교합니다.
5. 결과를 결정과 관련된 차트, 대시보드, 알림 또는 예약 보고서로 변환합니다.

Telemetry는 JSON 이벤트를 보내고, 추론된 테이블을 검사하고, DataFusion SQL을 실행하고, 결과를 게시하는 형태를 따릅니다. SQL 레시피 라이브러리는 입력된 계약, 합성 입력, 예상 출력, 차트 및 엣지 케이스를 사용하여 전체 경로를 검사할 수 있도록 합니다.

SQL이 옵저버빌리티에 유용한 이유

운영 질문은 로그로 시작하더라도 관계형이 되는 경우가 많습니다.

• 2026.07.28 출시 이후 어떤 경로가 느려졌습니까?
• 결제 사고로 인해 어떤 계정이 영향을 받았나요?
• 재시도가 웹훅 전달을 복구했습니까, 아니면 로드만 증가시켰습니까?
• 허용된 출력당 비용이 가장 높은 AI 기능은 무엇입니까?
• 표시 시간 초과 후 반복적으로 실패하는 대기열 작업은 무엇입니까?

이러한 질문에는 그룹화, 조건부 집계, 조인, 안정적인 ID 및 명시적인 시간 창이 필요합니다. SQL는 이러한 선택 사항을 표시합니다. 검토자는 요금이 행 또는 고유 요청을 사용하는지 여부, 최신 부분 버킷이 포함되는지 여부, 내부 조인이 일치하지 않는 데이터를 자동으로 제거하는지 여부를 확인할 수 있습니다.

SQL는 스킬로도 휴대 가능합니다. 함수 이름과 타임스탬프 구문은 엔진마다 다르지만 SELECT, WHERE, GROUP BY, CASE, 조인 및 창 함수는 내구성 있는 정신 모델을 형성합니다.

작업을 메시지가 아닌 이벤트로 모델링

API 요청, 체크아웃 시도, 백그라운드 작업, 웹훅 전달 또는 모델 응답과 같은 의미 있는 작업부터 시작하세요. 결과가 알려지면 하나의 터미널 이벤트를 내보냅니다.

{
  "event_name": "api_request_completed",
  "request_id": "req_01J...",
  "account_id": "acct_42",
  "route": "/v1/orders/:id",
  "method": "GET",
  "status_code": 503,
  "latency_ms": 842,
  "release": "2026.07.28",
  "region": "us-west",
  "outcome": "error",
  "error_type": "upstream_timeout"
}

이는 광범위한 이벤트입니다. 깨지기 쉬운 메시지 구문 분석 체인을 요구하지 않고 작업을 설명하는 데 필요한 컨텍스트를 유지합니다. route, error_type 및 outcome와 같은 필드에 제한된 범주를 사용합니다. 기본적으로 비밀, 원시 요청 본문, 프롬프트 텍스트 및 개인 고객 콘텐츠를 유지하세요.

Telemetry는 수집 중에 timestamp_utc를 추가합니다. 비즈니스 타임스탬프도 보내는 경우 모호한 두 번째 timestamp를 만드는 대신 scheduled_at, completed_at 또는 invoice_period_start와 같이 의미에 따라 이름을 지정합니다.

차원, 측정값 및 ID

실제 계약은 세 가지 종류의 분야를 구분합니다.

의도적으로 신원을 선택하십시오. 행 계산은 한 행이 계산하려는 단위와 동일한 경우에만 정확합니다. 재시도 원격 분석, 다단계 워크플로 및 정기적인 스냅샷은 일반적으로 하나의 논리 작업에 대해 여러 행을 생성합니다.

스키마 디자인에 대한 자세한 내용은 이벤트 스키마 설계, 상관 ID 및 높은 카디널리티 필드를 사용하세요.

5가지 SQL 패턴으로 다양한 조사 수행

1. 결정 창으로 필터링

SELECT *
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
  AND route = '/v1/orders/:id'
ORDER BY timestamp_utc DESC
LIMIT 200;

원시 행으로 시작합니다. 집계를 구축하기 전에 단위, Null 허용 여부, 경로 정규화 및 결과 값을 확인하세요.

2. 명시적인 분모를 사용하여 비율을 계산합니다.

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

분모는 모두 일치하는 요청 행입니다. 프로듀서가 재시도를 새 행으로 내보내는 경우 대시보드에 시도 또는 고유한 논리적 요청을 표시할지 여부를 결정합니다.

3. 릴리스 경계 비교

SELECT
  release,
  COUNT(*) AS requests,
  approx_percentile_cont(latency_ms, 0.95) AS p95_latency_ms,
  ROUND(
    100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END)
      / NULLIF(COUNT(*), 0),
    2
  ) AS error_rate_pct
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '7 days'
GROUP BY release
ORDER BY release;

릴리스 비교에는 트래픽 공유 및 출시 시간이 필요합니다. 소량의 카나리아를 완전한 프로덕션 출시로 해석해서는 안 됩니다.

4. 안정적인 계정에 기술 영향을 결합

SELECT
  r.account_id,
  a.plan,
  COUNT(*) AS failed_requests
FROM api_request_completed r
LEFT JOIN account_dimension a
  ON r.account_id = a.account_id
WHERE r.timestamp_utc >= now() - INTERVAL '2 hours'
  AND r.status_code >= 500
GROUP BY r.account_id, a.plan
ORDER BY failed_requests DESC;

왼쪽 조인은 강화가 늦어지더라도 영향을 받는 계정을 보존합니다. 차원의 최신성과 키당 한 행 규칙을 명시적으로 유지합니다.

5. 상호 연관된 타임라인 재구성

request_id, job_id 또는 다른 워크플로 식별자를 사용하여 이벤트를 시간 순서로 통합하거나 조인하세요. 타임라인은 시도, 재시도, 종속성 결과 및 최종 상태를 표시하므로 단일 집계보다 사고 발생 시 더 유용한 경우가 많습니다.

연결된 SQL 랩은 조인, 퍼널, AI 비용, 안정성 및 복구에 대한 6개의 합성 테이블과 안내 강의를 제공합니다. 브라우저에서 완전히 실행됩니다.

시각화를 질문과 연결하세요.

쿼리 결과에 따라 시각적 요소가 결정되어야 하며 그 반대가 아닙니다.

항상 차트 옆에 결과 테이블을 사용할 수 있도록 유지하십시오. 도구 설명과 축은 기본 행에서 눈에 띄는 반올림, Null 및 작은 분모를 숨길 수 있습니다.

모든 공개 Telemetry 레시피에는 크롤링 가능한 결과 테이블, 시각적 미리보기, JSON 및 CSV 고정 장치, 정적 차트가 포함되어 있습니다. API 경로별 오류율, 지문별 느린 데이터베이스 쿼리 또는 기능별 LLM 비용으로 시작하세요.

SQL이 다른 텔레메트리을 보완해야 하는 경우

저렴하고 지속적인 집계 신호와 엄격하게 제어되는 레이블을 통한 알림을 위해 메트릭을 사용하세요. 추적을 사용하여 요청의 분산된 중요 경로를 이해합니다. 정확한 진단 메시지가 중요하거나 형태를 미리 알 수 없는 경우 텍스트 로그를 사용합니다. 팀에 유연한 차원, 비즈니스 컨텍스트, 조인 또는 감사 가능한 계산이 필요한 경우 구조화된 이벤트 테이블을 사용하세요.

시스템은 상관 관계 ID를 공유할 수 있습니다. SQL 결과는 영향을 받는 릴리스 및 계정 집단을 식별할 수 있습니다. 그런 다음 추적을 통해 대표적인 느린 요청을 설명할 수 있습니다. 텍스트 로그는 정확한 종속성 오류를 표시할 수 있습니다.

지원하는 결정 없이 모든 추적 범위 또는 로그 줄을 두 번째 저장소에 복사하지 마세요. 중복 수집으로 인해 비용이 발생하고 정의가 충돌합니다.

안전한 입양 순서

불확실한 작업 흐름 하나를 선택하고 데이터가 뒷받침해야 하는 결정을 적어보세요. 터미널 이벤트를 정의하고, 섀도우 모드로 계측하고, 이벤트 수를 기존 소스와 비교하고, 원시 행을 검사합니다. 그런 다음 집계를 게시하십시오.

메시지 검색을 점진적으로 중단하려면 임시 로그에서 구조화된 이벤트 및 SQL로 마이그레이션을 따르세요. 현재 팀이 LogQL, KQL 또는 SPL를 사용하는 경우 쿼리 언어 마이그레이션 가이드는 언어가 상호 교환 가능한 것으로 가정하지 않고 공통 패턴을 매핑합니다.

체크리스트 검토

쿼리가 작동되기 전:

• 행 그레인과 분모를 확인합니다.
• null 및 지연 도착 행위를 문서화합니다.
• 시간 범위를 제한하고;
• 단위 및 타임스탬프 시간대를 확인합니다.
• 강화가 지연될 수 있는 경우 일치하지 않는 행을 보존합니다.
• 재시도 및 중복 횟수 계산 방법을 결정합니다.
• 불완전한 시간 버킷을 제외하거나 주석을 답니다.
• 과거 또는 합성 데이터에 대한 임계값을 테스트합니다.
• 차트에서 SQL 및 이벤트 계약으로의 링크를 유지합니다.

SQL 테스트 방법론은 Telemetry의 자동 검사가 무엇을 증명하고 비즈니스 판단이 여전히 필요한지를 설명합니다.