고성능 아키텍처 Snowpipe Streaming의 오류 로깅

Snowpipe Streaming의 오류 로깅은 Snowflake의 DML 오류 로깅 기능 위에 구축되어 데이터 수입 오류를 관리·복구하는 강력한 방법을 제공해요. 이 기능은 조용한 데이터 유실을 막고 잘못된 데이터 행에 대한 가시성을 높여 줍니다. 오류 로깅을 켜면 오류 없는 데이터는 계속 대상 테이블로 로드되고, 처리에 실패한 행은 검토·복구를 위해 자동으로 전용 오류 테이블로 라우팅됩니다.

출처: Snowflake 문서

본문

중요 오류 테이블에 저장된 데이터는 pipe 변환이 적용되기 전에 API나 SDK로 보낸 원래 페이로드입니다. pipe가 필드를 버리거나 변환하더라도 전체 원본 페이로드가 오류 테이블에 영속화됩니다.

개요

Snowpipe Streaming 고성능 아키텍처를 사용할 때 데이터 처리는 Snowflake에서 서버 측으로 일어납니다. 고성능 아키텍처는 암시적으로 ON_ERROR = CONTINUE 모드로 동작하며, 즉 유효한 행은 수입되고 문제가 있는 행은 건너뛰어집니다.

오류 처리 옵션

다음과 같은 방식으로 수입 오류를 모니터링·처리할 수 있어요.

오류 테이블 없이:

getChannelStatus()로 집계된 오류 수, 마지막 오류 메시지, 마지막 오류 타임스탬프를 모니터링하세요.
SNOWPIPE_STREAMING_CHANNEL_HISTORY 뷰를 조회해 과거 오류 추세와 패턴을 확인하세요.
이벤트 테이블 텔레메트리를 조회해 수입 진행 상황·처리 시간과 함께 행·채널 오류를 조사하세요.

이 모니터링 옵션들은 각 거부된 행의 완전한 원본 데이터가 아니라 개수와 오류 세부 정보를 제공합니다. 검사나 재처리에 그 데이터가 필요하면, 이 페이지에 설명된 캡처·크기 한도를 적용해 오류 테이블을 사용하세요.

오류 테이블과 함께:

처리에 실패한 행이 전용 오류 테이블에 자동으로 캡처됩니다.
각 오류 행에는 전체 원본 페이로드와 상세 오류 메타데이터가 포함됩니다.
표준 SQL로 실패한 행을 조회·분석·재처리할 수 있습니다.

오류 테이블은 정확히 어떤 행이 왜 실패했는지 보여 줌으로써 그림을 완성해, 완전한 디버깅과 복구를 가능하게 합니다.

오류 로깅 켜기

Snowpipe Streaming용 오류 로깅을 켜려면 대상 테이블에 ERROR_LOGGING 속성을 설정하세요. 오류 로깅을 켜고 구성하는 전체 세부사항은 테이블용 DML 오류 로깅 구성을 참고하세요.

-- 새 테이블의 경우:
CREATE TABLE my_streaming_table (...) ERROR_LOGGING = TRUE;

-- 기존 테이블의 경우:
ALTER TABLE my_streaming_table SET ERROR_LOGGING = TRUE;

오류 로깅을 켜면 같은 오류 테이블이 DML 문과 Snowpipe Streaming 수입 워크로드 양쪽의 오류를 포착합니다.

오류 테이블 조회

기본 테이블의 오류 테이블을 조회하려면 ERROR_TABLE 테이블 함수를 사용하세요. 오류 테이블 스키마, 액세스 제어, 지원 작업의 전체 세부사항은 오류 로깅과 오류 테이블을 참고하세요.

SELECT *
FROM ERROR_TABLE(my_streaming_table)
ORDER BY timestamp;

결과에는 수입 스트림의 잘못된 행마다 한 행이 포함됩니다.

Snowpipe Streaming 오류 필드

Snowpipe Streaming 오류는 DML 오류와 같은 오류 테이블 컬럼(timestamp, query_id, error_code, error_metadata, error_data)에 저장됩니다. error_metadata와 error_data 객체에는 Snowpipe Streaming용 추가 필드가 포함되며, 다음 절에서 설명합니다.

Snowpipe Streaming 오류 식별

error_metadata:service 필드는 Snowpipe Streaming의 오류에 대해 snowpipe_streaming으로 채워집니다. 이 필드로 소스별로 오류를 필터링하세요:

SELECT *
FROM ERROR_TABLE(my_streaming_table)
WHERE error_metadata:service = 'snowpipe_streaming';

오류 메타데이터 세부 정보

Snowpipe Streaming 오류의 경우 error_metadata:details 객체에 다음 추가 필드가 포함됩니다.

필드	설명
pipe_name	잘못된 행을 수입하는 데 사용된 pipe의 이름.
channel_name	잘못된 행을 수입하는 데 사용된 채널의 이름.
offset_token_lower_bound	잘못된 행을 포함하는 하한 offset token. 행이 이 offset token 또는 그 이후의 페이로드에 나타납니다. SDK 버전 1.4.0 이상 필요.
offset_token_upper_bound	잘못된 행을 포함하는 상한 offset token. 행이 이 offset token 또는 그 이전의 페이로드에 나타납니다.
error_data_truncated	원시 페이로드가 오류 테이블에 맞게 잘렸는지(최대 128 MB) 나타냅니다.
error_data_content_type	error_data 컬럼에 저장된 콘텐츠 유형을 나타냅니다. Error data content types를 참고하세요.

오류 데이터 형식

Snowpipe Streaming 오류의 경우 error_data:$1 필드에 잘못된 행을 나타내는 원시 페이로드가 포함됩니다. 페이로드에 잘못된 UTF-8 문자가 있으면 원시 페이로드가 base64 인코딩된 이진 문자열로 저장됩니다.

오류 데이터 콘텐츠 유형

error_data_content_type 필드는 만난 오류 유형을 나타내고 해결 단계를 제안합니다.

json

잘못된 행은 구문상 유효한 JSON 문자열이지만, 데이터를 대상 테이블로 수입하는 동안 논리적 오류가 발생했습니다. 일반적인 논리적 오류:

필수 non-nullable 컬럼 누락: NOT NULL 제약이 있는 필수 컬럼이 페이로드에 제공되지 않았습니다.
타입 변환 오류: JSON 데이터 타입을 대상 컬럼 타입으로 캐스트할 수 없습니다. 예를 들어 문자열 값 "abc"는 NUMBER 컬럼으로 변환할 수 없어요.
변환 오류: pipe 변환 표현식(예: 0으로 나누기)을 평가하는 동안 오류가 발생했습니다.

해결하려면 수입 오류를 일으킨 error_metadata:error_message의 오류 메시지와 error_metadata:error_source의 컬럼 이름을 검사하세요. PARSE_JSON(error_data:$1)로 페이로드를 파싱하고, 데이터를 수정한 뒤 대상 테이블에 다시 삽입하세요.

json-invalid

구문상 유효하지 않은 JSON 객체가 수입되었습니다. 해결하려면 구문 오류에 대한 세부 정보가 포함된 error_metadata:error_message의 오류 메시지를 검사하세요. error_data:$1에 저장된 페이로드를 수정하고 대상 테이블에 다시 삽입하세요.

binary-base64

잘못된 UTF-8 데이터가 수입되었습니다. 오류 페이로드는 오류 테이블에 base64 인코딩된 이진 문자열로 저장됩니다. 이 오류 유형은 보통 상위 데이터 소스의 형식 불일치나 인코딩 오류를 나타냅니다. 해결하려면 데이터 소스와 그 소스가 생성하는 데이터 형식·인코딩을 조사하세요. BASE64_DECODE_STRING 함수로 error_data:$1에 저장된 페이로드를 디코딩해 원시 바이트를 검사하고 잘못된 UTF-8 시퀀스를 식별하세요.

오류 복구 워크플로우

다음 예제는 오류를 조회하고, 분석하고, 수정된 데이터를 다시 삽입하는 방법을 보여 줍니다.

최근 오류 조회

SELECT timestamp,
    error_code,
    error_metadata:error_message::STRING AS error_message,
    error_metadata:details:channel_name::STRING AS channel,
    error_metadata:details:pipe_name::STRING AS pipe,
    error_metadata:details:error_data_content_type::STRING AS content_type,
    error_data:"$1"::STRING AS raw_payload
FROM ERROR_TABLE(my_streaming_table)
WHERE error_metadata:service = 'snowpipe_streaming'
AND timestamp >= DATEADD(hour, -1, CURRENT_TIMESTAMP())
ORDER BY timestamp DESC;

오류 분포 분석

SELECT error_code,
    error_metadata:error_message::STRING AS error_message,
    COUNT(*) AS error_count
FROM ERROR_TABLE(my_streaming_table)
WHERE error_metadata:service = 'snowpipe_streaming'
AND timestamp >= DATEADD(hour, -24, CURRENT_TIMESTAMP())
GROUP BY 1, 2
ORDER BY error_count DESC;

복구 가능한 오류 수정·재삽입

유효한 JSON 페이로드가 있는 오류의 경우 데이터를 파싱·수정·재삽입할 수 있어요:

INSERT INTO my_streaming_table (col1, col2, col3)
SELECT TRY_CAST(PARSE_JSON(error_data:"$1"):col1 AS NUMBER),
       PARSE_JSON(error_data:"$1"):col2::STRING,
       TRY_CAST(PARSE_JSON(error_data:"$1"):col3 AS TIMESTAMP)
FROM ERROR_TABLE(my_streaming_table)
WHERE error_metadata:service = 'snowpipe_streaming'
AND error_metadata:details:error_data_content_type = 'json'
AND timestamp >= DATEADD(hour, -24, CURRENT_TIMESTAMP());

오류를 성공적으로 재처리한 뒤 오류 테이블을 잘라낼 수 있어요:

TRUNCATE ERROR_TABLE(my_streaming_table);

청구

Snowpipe Streaming 수입은 표준 Snowpipe Streaming 요율로 청구됩니다. 오류 로깅을 켜도 수입 비용은 변하지 않아요. 실패한 행을 오류 테이블로 라우팅하는 데 추가 수입 요금은 없습니다.

Snowflake는 오류 테이블에 저장된 데이터에 대해 다른 테이블과 같은 표준 스토리지 요율로 청구합니다. 오류 테이블은 각 실패한 행의 원시 페이로드와 오류 메타데이터를 저장합니다. Snowpipe Streaming 비용에 대한 자세한 내용은 Snowpipe Streaming 고성능 아키텍처: 비용 이해를 참고하세요.

제한 사항

오류 테이블은 서버 측 데이터 처리(파싱과 변환) 중 발생하는 오류를 캡처합니다. 다른 단계(SDK 검증, API 실패, 기타 서버 측 비동기 오류)의 오류는 오류 테이블에 캡처되지 않아요. getChannelStatus()로 서버 측 비동기 오류를 모니터링하세요.
들어오는 행의 높은 실패율은 오류 정보 저장 오버헤드 때문에 처리 지연 시간을 늘릴 수 있습니다.
128 MB보다 큰 페이로드는 잘립니다. error_data_truncated 필드가 잘림이 발생했을 때를 나타냅니다.
오류 테이블은 Snowpipe Streaming 고성능 아키텍처에서만 사용할 수 있습니다. classic 아키텍처에서는 오류 처리가 SDK를 통해 클라이언트 측에서 관리됩니다.

고성능 아키텍처 Snowpipe Streaming의 오류 로깅