BigQuery Python UDF 로깅 활용법, 오류 행 추적과 복구

실무 맥락, 불량 행 하나에 쿼리가 멈추던 문제

마케팅 이벤트 수집 파이프라인에서는 JSON 페이로드가 깨져 들어오는 일이 흔해요. 필수 필드가 빠지거나 형식이 어긋난 행 하나 때문에 적재 쿼리 전체가 실패하면 원인 행을 찾는 일도 번거롭습니다. 이번 기능은 이런 상황에서 행 단위 진단 정보를 쿼리 실행 중에 바로 남기게 해줘요.

이번 내용, 검증과 격리와 복구의 3단계 흐름

원문은 e-commerce 이벤트(click, view, checkout) 수집 파이프라인을 예로 들어요. 흐름은 세 단계입니다.

• 인라인 검증: Python UDF가 JSON을 파싱하다 파싱에 실패하거나 필수 키가 없으면 logging.error()로 구조화된 진단 JSON을 남기고 NULL을 반환해요. 정상 행은 목적지 테이블로 넘어가고, 쿼리는 중단 없이 끝납니다. 원문 예시에서는 2번과 3번 행이 Cloud Logging으로 빠졌어요.
• 실시간 알림: Cloud Monitoring 로그 기반 지표로 오류율이 SLA 임계치를 넘으면 팀에 알립니다. Logs Explorer에서 UDF 루틴용 로그 필터를 붙여넣고 Create alert를 눌러 Slack, PagerDuty, 이메일 같은 알림 채널을 지정하면 돼요.
• SQL 진단과 재적재: Cloud Logging 버킷에서 BigQuery Log Analytics를 켜고 연결된 데이터셋을 만들면, 연결된 _AllLogs 뷰를 표준 SQL로 조회해 격리된 payload를 볼 수 있어요. 원본 payload 전체가 로그에 남아 있어서 상류 데이터를 고친 뒤 SQL로 복구해 다시 적재할 수 있습니다. 원문 결과는 정상 행과 복구 행이 모두 운영 테이블(clean_events)에 합쳐져 유실이 없다는 내용이에요.

실무 적용 체크리스트

• 로그를 남길 세션에서 SET @@udf.properties = JSON '{"enableDebugOutput": true}'; 를 먼저 실행하세요. 이 설정이 없으면 로그가 잡히지 않습니다.
• SQL로 로그를 조회하려면 Cloud Logging 버킷에서 BigQuery Log Analytics를 켜고 연결 데이터셋을 만들어야 해요.
• Cloud Logging은 Logging Viewer 권한이 있는 사용자에게 보입니다. 자격 증명이나 비밀값, 민감정보는 로그에 남기지 마세요.
• 대용량 파이프라인에서는 오류 시점에만 남기거나 샘플링으로 로그 적재량을 조절해 비용을 관리하세요.

확장 활용

원문은 오류 격리 외에 세 가지 활용도 소개해요. 기존 로직과 신규 로직을 UDF 안에서 나란히 돌려 기존 결과는 운영에 반환하고 계산 차이만 로그로 남기는 섀도 실행, 민감 토큰을 마스킹해 BigQuery에 쓰면서 익명화된 감사 이벤트를 로그로 남기는 개인정보 처리 감사, 내장 스코어링 로직이 어휘 밖 입력이나 낮은 모델 신뢰도를 만났을 때 경고를 남기는 ML 추론 드리프트 모니터링입니다.

자주 묻는 질문

BigQuery 란 무엇인가요

Google Cloud의 데이터 분석용 데이터 웨어하우스예요. SQL로 대용량 데이터를 쿼리하고, 이번 글처럼 Python UDF로 SQL에 파이썬 로직을 얹을 수도 있습니다.

BigQuery Python UDF에서 로그는 어디에 남나요

Cloud Logging에 구조화된 로그로 남아요. 세션에서 enableDebugOutput을 켜야 하고, BigQuery Log Analytics와 연결 데이터셋을 만들어 두면 _AllLogs 뷰를 SQL로 조회할 수 있습니다.

불량 행 때문에 쿼리 전체가 실패하지 않으려면 어떻게 하나요

UDF 안에서 파싱 실패나 필수 필드 누락을 잡아 logging.error()로 기록하고 NULL을 반환하게 짜면 돼요. 정상 행은 계속 처리되고 문제 행만 로그로 격리됩니다.

로그가 너무 많이 쌓이면 어떻게 하나요

대용량 파이프라인에서는 모든 행을 남기지 말고 오류가 난 경우에만 기록하거나 샘플링으로 줄이세요. 로깅 적재량이 곧 비용이라서 선별 기록이 권장돼요.