구조화된 로깅 가이드

구조화된 로깅은 모든 세부 사항을 문장에 배치하는 대신 이벤트를 명명된 필드로 기록합니다. checkout failed for account 42 after 812 ms와 같은 메시지는 읽을 수 있지만 SQL는 오류를 그룹화하거나 대기 시간을 계산하기 전에 메시지를 구문 분석해야 합니다. 구조화된 이벤트는 event_name, account_id, status, error_type 및 latency_ms를 별도로 저장합니다.

질문으로 시작하세요

필드를 선택하기 전에 운영 또는 제품 관련 질문을 적어보세요. "가장 자주 실패하는 결제 단계는 무엇인가요?" 안정적인 단계 이름, 상태, 오류 범주 및 타임스탬프를 의미합니다. “어떤 고객이 영향을 받았나요?” 또한 안전한 계정 식별자가 필요합니다. 필터, 그룹, 계산 또는 디버깅 용도가 없는 필드는 노이즈일 수 있습니다.

의미 있는 경계에 있는 하나의 이벤트(예: 요청 완료, 작업 재시도 소진, 웹후크 중복 제거 또는 사용자가 활성화 마일스톤 도달)를 선호합니다. 동일한 워크플로의 모든 분기에 대해 다른 테이블을 내보내지 마세요. 일관된 status 필드를 통해 성공과 실패를 비교할 수 있습니다.

await telemetry.log("checkout_completed", {
  checkout_version: "v2",
  account_id: account.id,
  status: "failed",
  error_type: "payment_declined",
  latency_ms: 812,
  attempt: 1,
});

계약을 안정적으로 유지

snake_case 이름, _ms 및 _bytes와 같은 명시적 단위, UTC 타임스탬프를 사용하세요. 신뢰할 수 있는 그룹화 차원을 원하는 경우 전체 예외 텍스트가 아닌 payment_declined와 같은 범주를 저장합니다. 시스템 전체에서 요청, 계정, 릴리스 또는 작업을 추적할 수 있도록 이벤트 전체에서 식별자를 일관되게 유지하세요.

필드를 숫자에서 문자열로 자동으로 변경하지 마세요. 의미가 변경되면 버전 필드나 새 이벤트 계약을 추가하세요. 이벤트 스키마 디자인 가이드에서는 명명, 소유권 및 진화에 대해 자세히 설명합니다.

민감한 데이터 보호

모든 새 필드를 쿼리 결과, 대시보드 또는 내보내기에 나타날 수 있는 데이터로 처리합니다. 자격 증명, 쿠키, 인증 헤더, 전체 요청 본문, 결제 세부정보 또는 원시 프롬프트를 보내지 마세요. 이메일과 자유 형식의 사용자 콘텐츠보다 내부 식별자와 통제된 카테고리를 선호하세요. 이벤트 구성 경계에 허용 목록을 적용합니다. 수집 후 수정은 기본 제어가 아니라 대체입니다.

이벤트 확인

합성 데이터를 사용하여 성공, 실패, 시간 초과 및 재시도 분기를 연습합니다. 결과 테이블을 검사하고, 필드 유형을 확인하고, 이벤트에 동기를 부여한 쿼리를 실행합니다. 그런 다음 결과가 비즈니스 정의와 일치한 후에만 시각화 또는 알림을 만듭니다.

구조화된 로그 관리 가이드, 표준 와이드 이벤트, 구조화된 이벤트와 텍스트 로그 비교를 계속 진행하거나 SQL 레시피 라이브러리에서 전체 쿼리를 복사하세요.