스키마 진화

이벤트 스키마를 변경하면 이를 쓰는 전송 코드, 쿼리, 대시보드, 알림, 내보내기가 작동하지 않을 수 있습니다. Telemetry는 사전 마이그레이션 없이 새 JSON 필드를 받습니다. 기존 필드의 유형이나 의미를 바꿀 때는 이전 정의를 쓰는 코드와 저장된 행을 어떻게 처리할지 계획해야 합니다.

기존 필드의 의미와 유형을 유지하세요. 둘 중 하나를 바꿔야 한다면 새 필드나 버전을 추가하세요.

호환성 매트릭스

데이터를 추가하는 것은 기술적으로 쉽습니다. 호환성은 모든 다운스트림 정의, 특히 제어된 값, 단위, 행 단위, ID 및 시간 의미에 따라 달라집니다.

소비자를 중단하지 않고 필드 추가

api_request_completed가 이미 다음을 기록하고 있다고 가정합니다.

{
  "event_id": "evt_api_01",
  "route": "/v1/query/:id",
  "status_code": 200,
  "latency_ms": 184,
  "release": "2026.07.2"
}

제한된 실패 범주를 추가하고 싶습니다.

{
  "event_id": "evt_api_02",
  "route": "/v1/query/:id",
  "status_code": 503,
  "latency_ms": 921,
  "release": "2026.07.3",
  "error_type": "upstream_unavailable"
}

단계별 배포:

1. 허용되는 값, 개인 정보 보호 클래스, 소유자 및 필드를 설정하는 분기를 문서화합니다.
2. error_type 및 각 예상 실패 범주 없이 성공을 위한 고정 장치를 추가합니다.
3. 기존 쿼리가 여전히 필드를 무시하는 동안 프로듀서를 해제합니다.
4. 릴리스 및 상태별로 현장 적용 범위를 측정합니다.
5. 충분한 관련 행에 대시보드 및 알림이 포함된 후에만 대시보드 및 알림을 업데이트하세요.
6. 최소한 유지된 마이그레이션 기간 동안 쿼리가 이전 행을 허용하도록 유지하세요.

로그 API는 null 값, 빈 개체 및 빈 배열을 제거합니다. 따라서 "존재하지 않음"은 값이 없는 선택적 필드에 대해 예상되는 저장 상태입니다.

분야에 따라 달라지기 전에 채택 여부를 측정하세요.

부분적으로 마이그레이션된 코드를 찾으려면 릴리스 또는 명시적 프로듀서 버전을 사용하세요.

SELECT
  release,
  COUNT(*) AS failed_requests,
  SUM(CASE WHEN error_type IS NULL THEN 1 ELSE 0 END) AS missing_error_type,
  100.0 * SUM(CASE WHEN error_type IS NULL THEN 1 ELSE 0 END)
    / NULLIF(COUNT(*), 0) AS missing_rate_pct
FROM api_request_completed
WHERE status_code >= 500
  AND timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY release
ORDER BY release;

모든 오래되고 누락된 값에 대해 "없음"이 의도된 범주가 아닌 이상 COALESCE(error_type, 'none')를 사용하지 마십시오. 깨진 프로듀서 롤아웃을 숨길 수 있습니다.

필드 이름 바꾸기, 이동 또는 재정의

latency_ms의 이름을 duration_ms로 바꾸는 것은 저장된 이벤트 데이터의 내부 이름 바꾸기가 아닙니다. 이중 쓰기 마이그레이션을 사용합니다.

{
  "latency_ms": 184,
  "duration_ms": 184,
  "schema_version": 2
}

마이그레이션 기간 동안 우선순위를 명시적으로 지정하세요.

SELECT
  route,
  approx_percentile_cont(
    COALESCE(duration_ms, latency_ms),
    0.95
  ) AS p95_duration_ms
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '7 days'
GROUP BY route;

그런 다음:

1. 저장된 모든 쿼리, 대시보드, 알림, 내보내기 및 소비자를 업데이트합니다.
2. 현재 프로듀서가 이전 필드만 보내는지 확인합니다.
3. 합의된 호환성 기간을 기다리십시오.
4. 이전 필드 쓰기를 중지합니다.
5. 유지된 이전 행에 대한 기록 쿼리 동작을 문서화합니다.

쿼리가 안정적인 필드 이름을 대체하는 것이 아니라 정의를 구별해야 하는 경우 schema_version를 사용하세요. 버전은 행 단위, 결과 의미 또는 중첩 구조가 함께 변경될 때 특히 유용합니다.

필드 유형을 그대로 변경하지 마세요.

이 변경 사항은 안전하지 않습니다.

{ "account_id": 8421 }

{ "account_id": "acct_8421" }

두 번째 프로듀서는 첫 번째 프로듀서가 설정한 숫자 account_id와 충돌합니다. 저장소 계층이 두 값을 별도로 나타낼 수 있는 경우에도 조인과 필터는 더 이상 신뢰할 수 있는 하나의 유형을 공유하지 않습니다.

account_key와 같은 새 문자열 필드를 추가하고 검토되고 결정적인 매핑이 있는 경우에만 백필하고 소비자를 마이그레이션합니다. 동일한 규칙이 다음에도 적용됩니다.

• 형식화된 문자열로 전송된 숫자 기간;
• 부울은 "yes" 및 "no"로 대체되었습니다.
• 타임스탬프는 로캘별 문자열로 대체됩니다.
• 객체에서 스칼라로 변경되는 하나의 중첩 경로;
• 한 엔터티 유형에서 다른 엔터티 유형으로 변경되는 식별자입니다.

상태 값을 스키마로 처리

이전에 success 또는 failed로 문서화된 필드에 cancelled를 추가해도 해당 문자열 유형은 변경되지 않지만 여전히 논리가 중단될 수 있습니다.

SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END)

쿼리는 자동으로 cancelled를 실패하지 않은 것으로 처리합니다. 새 값을 내보내기 전에 실패, 제외 또는 별도의 결과에 속하는지 여부를 결정하세요. 철저한 상태 필터에 대한 쿼리 레지스트리를 검색하고 먼저 픽스처를 업데이트하세요.

출시 및 롤백 검증

제작 전 대표 이벤트 테스트:

배포 후 릴리스별로 허용된 이벤트 볼륨, 필수 필드 적용 범위, 제어된 값 분포 및 주요 쿼리 결과를 비교합니다. 롤백은 이전 프로듀서가 설정된 스키마를 계속 작성할 수 있고 새 소비자가 누락된 필드를 허용하는 경우에만 안전합니다.

기록 데이터 및 백필

스키마 진화는 미래의 사건을 변화시킵니다. 보유 내역을 자동으로 다시 쓰지 않습니다. 백필 전:

• 진실과 결정론적 변환의 정확한 소스를 정의합니다.
• 원래 이벤트 시간과 안정적인 식별자를 보존합니다.
• 이벤트 또는 마이그레이션 식별자로 중복을 방지합니다.
• 제한된 간격으로 행 수를 테스트하고 총계를 집계합니다.
• 어떤 날짜와 버전이 재작성되었는지 기록합니다.
• 대시보드에 혼합 기록 또는 백필 기록을 표시할지 여부를 결정합니다.

이전 데이터가 새로운 의미를 지원할 수 없는 경우 누락된 상태로 두고 적용 범위 경계를 표시합니다. 가치를 창조하면 차트가 더 깔끔해지지만 분석의 신뢰성은 떨어집니다.

스키마 변경 체크리스트

1. 현재 및 제안된 행 단위, 유형, 단위 및 의미를 명시합니다.
2. 인벤토리 프로듀서 및 모든 다운스트림 쿼리, 대시보드, 알림 및 내보내기.
3. 추가 필드를 선호합니다. 그레인 변경을 위해 새로운 이벤트나 버전을 사용하세요.
4. 성공, 실패, 누락, 재시도 및 롤백 픽스처를 추가합니다.
5. 둘 다 변경해야 하는 경우 새 작성자보다 먼저 호환 가능한 리더를 배포합니다.
6. 출시가 완료되었다고 가정하는 대신 릴리스별 채택을 측정하세요.
7. 문서화된 이중 읽기 또는 이중 쓰기 창을 유지합니다.
8. 사용 및 보유 기록 동작을 이해한 후에만 이전 경로를 제거하십시오.

이벤트 데이터 유형 및 null 허용 여부, 중첩된 JSON 쿼리, 이벤트 스키마 카탈로그 및 필수 필드 null 비율 레시피를 계속 진행하세요.