Snowflake Connector for Kafka 문제 해결

Snowflake Connector for Kafka 문제 해결 (Troubleshoot the Snowflake Connector for Kafka)

이 문서는 Snowflake Connector for Kafka("Kafka 커넥터")를 사용할 때 발생하는 일반적인 문제를 해결하는 방법을 설명해요.

출처: Troubleshoot the Snowflake Connector for Kafka

본문

사용할 로그 파일

커넥터 문제를 진단할 때 다음 로그 파일을 확인하세요:

Connect 로그 파일: Kafka Connect 작업자의 로그. 커넥터가 던지는 대부분의 오류가 여기에 기록돼요. Snowflake 관련 오류 메시지는 대개 com.snowflake.kafka.connector... 문자열을 포함해요.
Snowpipe / 로드 활동: COPY_HISTORY 뷰로 로드 활동을 확인하세요.

Kafka Connect 로그에서 오류 확인

Kafka Connect 로그에서 ERROR 문자열과 함께 파일 이름 com.snowflake.kafka.connector...을 포함하는 메시지를 검색하세요. 만날 수 있는 일반적인 오류 유형은 다음과 같아요:

구성 오류

커넥터가 토픽을 구독할 충분한 정보를 가지지 못함 (예: topics 속성 누락).
커넥터가 Snowflake에 쓸 충분한 정보를 가지지 못함 (예: 잘못된 키 페어, 잘못된 계정 URL).

커넥터는 파라미터를 검증하고 호환되지 않는 각 구성 파라미터에 대해 오류를 던져요. 오류 메시지는 Kafka Connect 클러스터의 로그 파일에 기록돼요. 구성 문제가 의심되면 해당 로그 파일을 확인하세요.

읽기 오류

커넥터가 Kafka에서 읽지 못할 수 있어요. 가능한 원인:

Kafka 또는 Kafka Connect가 실행 중이지 않음.
메시지가 아직 전송되지 않음.
메시지가 만료되어 삭제됨.

쓰기 오류 (스테이지)

스테이지에 대한 권한 부족.
스테이지 공간 부족.
스테이지가 삭제됨.
다른 사용자/프로세스가 예상치 못한 파일을 스테이지에 썼음.

쓰기 오류 (테이블)

테이블에 대한 권한 부족.

COPY_HISTORY로 오류 확인

COPY_HISTORY 뷰의 STATUS 컬럼은 파일이 로드되었는지, 부분 로드되었는지, 실패했는지 나타내고, FIRST_ERROR_MESSAGE는 실패 원인을 제공해요.

테이블 스테이지에 로드되지 않은 파일이 보이면:

LIST @mydb.public.%mytable;

테이블 스테이지의 파일을 검증하려면 파일을 로컬로 다운로드(GET)하고, 같은 형식의 내부 스테이지에 업로드(PUT)한 뒤 VALIDATION_MODE = 'RETURN_ALL_ERRORS'로 COPY INTO를 실행하세요. 표시된 오류를 해결한 후 VALIDATION_MODE 없이 다시 로드하세요.

자주 묻는 문제

같은 토픽 파티션/오프셋의 중복 행

동일한 토픽 파티션과 오프셋을 가진 중복 행은 로드 작업이 기본 실행 제한인 300000ms(300초)를 초과했음을 나타낼 수 있어요. 해결하려면 Kafka 구성 파일에서 다음 중 하나를 변경하세요:

consumer.max.poll.interval.ms를 900000(900초)으로 증가.
consumer.max.poll.records를 50으로 감소.

스트리밍 채널 오프셋 마이그레이션 오류 (5023)

Snowpipe Streaming 채널 이름 형식 변경으로 인해 v2.1.0 이상으로 업그레이드한 커넥터에서 Failure in Streaming Channel Offset Migration Response Error Code: 5023 오류가 발생할 수 있어요. 해결하려면 Kafka 구성 파일에 다음 속성을 추가해 자동 오프셋 마이그레이션을 비활성화하세요:

enable.streaming.channel.offset.migration=false

도움 요청 시 준비할 파일

Snowflake Support에 연락할 때 다음 파일을 준비하세요:

커넥터 구성 파일 (프라이빗 키 제거 후).
Kafka 커넥터 로그 사본 (기밀 정보 제거).
JDBC 로그 (Kafka Connect에서 JDBC_TRACE=true 설정 후 생성).
Connect 로그 파일.

Snowflake Connector for Kafka 문제 해결