빅쿼리 Python UDF 로그, Cloud Logging에서 보는 방법

빅쿼리 Python UDF 로깅은 UDF 안에서 파이썬 표준 logging으로 남긴 기록을 Cloud Logging에서 볼 수 있게 하는 기능이다. 구글 클라우드는 2026년 10월 20일 공식 블로그에서 이 방법을 소개했고, 쿼리 실행 전에 세션에서 enableDebugOutput을 켜면 된다. 로그는 기본으로 꺼져 있다.

빅쿼리 Python UDF 로그가 필요한 상황

수백만 행을 UDF로 처리하다 쿼리가 한 행 때문에 통째로 실패하면 어느 행이 문제였는지 찾기가 막막하다. 택배 분류장에서 상자 하나가 걸려 컨베이어 벨트가 멈췄는데 어느 상자인지 알 수 없는 것과 비슷하다. 문제 상자에 송장 메모를 붙여 옆 칸에 빼 두면 벨트는 계속 돌고, 나중에 메모만 보고 원인을 찾을 수 있다. UDF 로깅이 이 메모 역할을 한다. 다만 메모에 고객 정보를 그대로 적으면 메모를 볼 수 있는 사람 모두에게 노출된다.

구글 클라우드 블로그의 예시는 잘못된 JSON을 만났을 때 오류를 로그로 남기고 None(SQL에서는 NULL)을 돌려주는 UDF다. 이렇게 하면 문제 레코드는 따로 격리되고 쿼리 전체는 중단되지 않는다.

Python UDF에서 logging 켜는 방법

빅쿼리 공식 문서에 따르면 Python UDF 로깅은 데이터 유출을 막으려고 기본으로 꺼져 있다. 쿼리를 실행하기 전에 같은 세션에서 아래 문을 먼저 실행한다.

SET @@udf.properties = JSON '{"enableDebugOutput": true}';

그다음 UDF 안에서 logging 라이브러리를 쓴다. 공식 문서는 print()가 지원되지 않는다고 적고 있으니, 기존 UDF에 print로 찍어 둔 곳이 있으면 logging으로 바꿔야 한다. 런타임은 python-3.11만 지원된다.

CREATE OR REPLACE FUNCTION `YOUR_PROJECT.YOUR_DATASET.safe_parse_json`(
  raw_payload STRING, required_key STRING
) RETURNS STRING
LANGUAGE python
OPTIONS (entry_point='safe_parse_json', runtime_version='python-3.11')
AS r'''
import json
import logging

def safe_parse_json(raw_payload, required_key):
    try:
        data = json.loads(raw_payload)
        if required_key and (required_key not in data or data[required_key] is None):
            logging.error(json.dumps({
                "error_type": "MISSING_REQUIRED_KEY",
                "missing_key": required_key,
                "raw_payload": raw_payload[:200]
            }))
            return None
        return json.dumps(data)
    except Exception as e:
        logging.error(json.dumps({
            "error_type": "JSON_SYNTAX_ERROR",
            "error_message": str(e),
            "raw_payload": raw_payload[:200]
        }))
        return None
''';

이 코드는 구글 클라우드 블로그 예시를 줄인 것이다. 로그를 json.dumps로 만든 JSON 문자열로 남기면 뒤에서 SQL로 오류 종류별 집계를 하기 쉽다.

빅쿼리 UDF 로그 확인하는 위치

로그는 Cloud Logging의 bigquery.googleapis.com/ManagedRoutineInvocation 리소스에 기록된다. 공식 문서가 안내하는 확인 경로는 세 가지다.

확인 방법	어디서 어떻게
쿼리 작업 정보	빅쿼리에서 해당 쿼리 작업의 정보 탭에 있는 Log 링크를 연다.
Logs Explorer	resource.type="bigquery.googleapis.com/ManagedRoutineInvocation" severity>=ERROR로 필터링하고, 특정 실행만 보려면 query_job_id 라벨로 좁힌다.
SQL 조회	Cloud Logging 버킷에서 Log Analytics를 켜고 연결 데이터셋을 만든 뒤 _AllLogs 뷰를 조회한다.

SQL로 조회하면 오류 종류별로 몇 건이 났는지 바로 셀 수 있다. 구글 클라우드 블로그의 예시 쿼리는 아래와 같다.

SELECT timestamp, severity,
       JSON_VALUE(json_payload.error_type) AS error_type,
       JSON_VALUE(json_payload.missing_key) AS missing_key,
       JSON_VALUE(json_payload.raw_payload) AS raw_payload
FROM `YOUR_PROJECT.YOUR_LOGS_LINKED_DATASET._AllLogs`
WHERE log_name LIKE '%managed_routine_output%'
ORDER BY timestamp DESC
LIMIT 10;

성공 여부는 Logs Explorer에서 방금 실행한 query_job_id로 필터링했을 때 UDF 안에서 남긴 JSON 메시지가 보이는지로 판단한다. 아무것도 안 보이면 SET @@udf.properties를 쿼리와 같은 세션에서 실행했는지부터 확인한다.

알림 설정과 로그 비용·보안 주의점

구글 클라우드 블로그에 따르면 Logs Explorer에서 Create alert를 눌러 Slack, PagerDuty, 이메일 같은 채널로 오류 알림을 받을 수 있고, 이 알림은 Cloud Monitoring의 로그 기반 지표로 동작한다.

주의할 점은 둘이다. 첫째, 로그 데이터는 Google Cloud Observability 요금 체계를 따른다. 공식 문서는 예외 상황, 데이터 이상 징후, 특정 디버깅 기간에만 로깅하라고 권한다. 블로그도 처리량이 많은 파이프라인에서는 오류만 남기거나 샘플링하라고 안내한다. 둘째, 로그를 볼 권한이 있는 사용자는 해당 데이터에 대한 빅쿼리 권한이 없어도 기록된 내용을 볼 수 있다. 그래서 예시처럼 원문을 앞 200자만 남기거나, 개인정보와 비밀 값은 아예 기록하지 않는 편이 안전하다.

이 글을 쓴 10월 20일 기준으로 공식 블로그와 문서는 출시 단계(프리뷰·정식)를 따로 밝히지 않는다. 조직에서 쓰기 전에 문서의 최신 표기를 한 번 확인한다.

자주 묻는 질문

UDF 안에서 print로 찍으면 안 되나요?

공식 문서는 Python UDF에서 print()가 지원되지 않는다고 안내한다. logging.info나 logging.error를 쓴다.

로그를 켜 두면 항상 비용이 드나요?

로그는 Cloud Logging에 저장되므로 Google Cloud Observability 요금이 적용된다. 기본값이 꺼짐이고, 오류 행만 남기면 양을 줄일 수 있다.