포스트

Structured Streaming은 Kafka 오프셋을 어디 둘까

Structured Streaming은 Kafka 오프셋을 어디 둘까

Spark에는 스트리밍 API가 두 개 있다. RDD 위에서 도는 Spark Streaming(DStream)과 DataFrame 위에서 도는 Structured Streaming이다. 둘 다 마이크로배치로 돌지만, Kafka를 어디까지 읽었는지 기억하는 곳과 출력이 몇 번 쓰이는지가 다르다. Spark Streaming으로 Hive에 쌓는 글의 DStream 잡을 예로 두고, 그 잡을 Structured Streaming으로 옮긴다고 가정해 무엇을 얻고 무엇을 내주는지 정리한다. 실제로 옮긴 잡은 아니고, 아래의 전환은 모두 가정이다. 버전은 Spark 4.3 기준이다.

두 API를 한 표로

 DStream (Kafka 0-10 direct stream)Structured Streaming
실행 단위batch interval마다 RDD 하나트리거마다 마이크로배치 하나, 결과 테이블을 증분으로 갱신
코드foreachRDD 안에서 RDD를 직접 다룸DataFrame 연산과 writeStream
Kafka 오프셋체크포인트, Kafka 커밋, 외부 저장소 중에서 고름체크포인트의 오프셋 로그. Kafka에는 커밋하지 않음
컨슈머 그룹직접 지정쿼리마다 고유한 그룹을 자동으로 만듦
파일 출력at-least-once, 멱등하게 만드는 건 사용자 몫파일 싱크는 exactly-once
이벤트 시간직접 구현withWatermark, window
현재 상태업데이트가 끝난 legacy 프로젝트Spark의 현재 스트리밍 엔진

DStream은 Spark 2.0에서 Structured Streaming이 나오기 전부터 쓰이던 API다. Kafka direct stream은 Kafka 파티션 하나를 RDD 파티션 하나로 대응시키는 단순한 구조이고, 그 잡도 20초 batch interval로 토픽을 읽어 배치마다 HDFS 파일에 붙여 썼다.

오프셋은 어디에 남는가

DStream의 Kafka 0-10 연동은 오프셋을 체크포인트, Kafka 커밋, 결과와 같은 트랜잭션 저장소 중 어디에 둘지 사용자에게 맡기고, Hive 적재 글의 잡이 자동 커밋에 일 배치 dropDuplicates()와 복구 모드를 묶어 스트리밍 쪽을 단순하게 둔 구조는 Kafka 전달 보장 글에 정리했다.

Structured Streaming의 Kafka 소스는 이 선택지를 없앴다. auto.offset.reset, enable.auto.commit은 예외가 나고, kafka.group.id는 경고와 함께 허용되지만 그 그룹의 커밋 오프셋은 읽지 않는다. 쿼리는 트리거마다 처리한 오프셋 범위를 체크포인트 디렉터리에 먼저 기록하고, 재시작하면 거기서 이어 읽는다. startingOffsets(스트리밍 기본값 latest)는 체크포인트가 없는 새 쿼리를 시작할 때만 쓰인다.

옮길 때 놓치기 쉬운 부분이 여기다. 새 쿼리는 예전 컨슈머 그룹의 커밋 오프셋을 보지 않는다. 예전 잡이 멈춘 자리부터 읽으려면 그 그룹의 오프셋을 조회해 startingOffsets에 파티션별 JSON({"logs":{"0":1234,"1":5678}})으로 넣어야 한다. 그냥 띄우면 기본값 latest라서 두 잡 사이에 들어온 메시지를 건너뛴다.

출력 모드와 파일 싱크의 exactly-once

Structured Streaming은 입력을 계속 늘어나는 테이블로 보고, 트리거마다 결과 테이블에서 무엇을 내보낼지를 출력 모드로 정한다.

출력 모드내보내는 것쓸 수 있는 쿼리
append (기본)새로 추가된 행만, 한 번씩이미 나간 행이 바뀌지 않는 쿼리. 집계라면 이벤트 시간 워터마크가 있어야 한다
update지난 트리거 뒤 바뀐 행집계, mapGroupsWithState, 집계 없는 쿼리
complete결과 테이블 전체집계 쿼리

파일 싱크는 append만 받고, 장애가 나도 exactly-once다. 출력 경로 아래 _spark_metadata 디렉터리에 배치마다 어떤 파일을 커밋했는지 로그를 남기고, 재시작 뒤 이미 커밋된 배치 ID가 다시 오면 쓰지 않고 건너뛴다. Kafka처럼 다시 읽을 수 있는 소스와 이 싱크를 묶으면 Kafka 재전달로 생기는 중복 줄이 파일에 남지 않는다.

이 보장에는 범위가 있다. _spark_metadata를 읽는 건 Spark의 파일 소스이고, 그것도 출력 루트 경로 하나를 줄 때다. dt=2026-11-19 같은 파티션 하위 폴더를 직접 읽거나, Hive처럼 폴더의 파일을 그대로 나열하는 쪽은 이 로그를 보지 않는다. 실패한 배치가 남긴 파일까지 읽을 수 있다는 뜻이다. 일 배치가 이 출력을 읽는다면 루트 경로를 읽고 dt로 거르는 편이 맞다.

같은 출력 경로에 체크포인트만 새로 만들어 붙이는 것도 위험하다. 새 쿼리의 배치 ID는 0부터 다시 시작하는데, 싱크는 _spark_metadata에 기록된 마지막 배치 ID 이하를 이미 커밋된 것으로 보고 건너뛴다. 에러 없이 데이터만 빠진다. 파일 싱크의 출력 경로를 바꾸는 변경도 재시작 시 허용되지 않는다.

이벤트 시간과 워터마크

DStream 잡은 메시지의 첫 이벤트 시각을 꺼내 분 단위 키로 만들고, 그 키의 파일에 붙여 썼다. 늦게 온 로그도 자기 시각의 파일로 간다. Structured Streaming에서는 이벤트 시각으로 파티션 컬럼을 만들고 partitionBy로 쓰면 같은 효과가 난다. 집계가 없는 쿼리라 워터마크는 필요 없다.

워터마크는 상태를 들고 있는 연산에서 필요하다. withWatermark("event_ts", "2 hours")는 지금까지 본 가장 큰 이벤트 시각에서 2시간을 뺀 값을 기준으로, 그보다 늦지 않은 데이터는 버리지 않겠다는 약속이다. 2시간보다 늦은 데이터는 반영될 수도 있고 버려질 수도 있다. Flink 시간과 윈도 글의 Flink 워터마크는 그보다 이른 이벤트가 더 오지 않는다는 선언이지만, Spark 쪽은 지연보다 덜 늦은 이벤트를 버리지 않는다는 데까지만 보장한다. 워터마크가 있어야 지난 윈도와 중복 판단 상태를 지울 수 있고, append 모드 집계는 워터마크가 윈도 끝을 지난 뒤에야 그 윈도 결과를 내보낸다.

일 배치의 중복 제거를 스트림 안으로 옮기는 방법도 있다. dropDuplicatesWithinWatermark(["line"])은 워터마크 지연 안에서 같은 값을 걸러 내고, 워터마크보다 늦게 온 행은 중복이 아니어도 통째로 버린다. 그 잡은 7일까지 늦게 오는 로그를 받았으니, 늦은 로그를 잃지 않으려면 지연을 7일로 두고 7일치 줄을 상태로 들고 있어야 한다. 일 배치는 이런 상태 없이 하루 폴더를 한 번 읽어 같은 줄을 지운다. 대신 일 배치가 돈 뒤에 들어온 늦은 로그는 그 정리에서 빠진다.

트리거: 20초 간격과 availableNow

트리거동작
지정 안 함앞 배치가 끝나자마자 다음 배치
processingTime="20 seconds"20초 경계마다 배치. 앞 배치가 20초를 넘기면 끝나자마자 바로 다음 배치. 새 데이터가 없으면 배치를 만들지 않음
availableNow=True시작 시점까지 쌓인 데이터를 소스 옵션에 맞춰 여러 배치로 나눠 처리하고 멈춤
once=True한 배치로 처리하고 멈춤. deprecated, availableNow로 대체

예전 잡의 20초 batch interval은 processingTime으로 옮기면 된다. 복구 모드는 availableNow와 잘 맞는다. 새 체크포인트, 별도 출력 경로, startingOffsets="earliest"로 쿼리를 띄우면 그 시점까지의 메시지를 다 읽고 스스로 끝난다. 출력 경로를 따로 두는 이유는 앞 절의 배치 ID 문제 때문이다.

옮긴다면

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 구조만 보여 주는 스케치, Spark 4.3 PySpark. 토픽, 경로, JSON 필드는 예시다
from pyspark.sql import functions as F

lines = (spark.readStream.format("kafka")
         .option("kafka.bootstrap.servers", "broker:9092")
         .option("subscribe", "logs")
         .option("startingOffsets", '{"logs":{"0":1234,"1":5678}}')  # 새 체크포인트일 때만 쓰인다
         .load()
         .selectExpr("CAST(value AS STRING) AS line"))

event_ts = F.coalesce(
    F.try_to_timestamp(F.get_json_object("line", "$.events[0].time")),
    F.current_timestamp())  # 시각을 못 읽으면 현재 시각, 예전 잡과 같은 처리

query = (lines
         .withColumn("dt", F.date_format(event_ts, "yyyy-MM-dd"))
         .withColumn("hr", F.date_format(event_ts, "HH"))
         .writeStream.format("text")
         .partitionBy("dt", "hr")
         .option("path", "hdfs:///logs/raw")
         .option("checkpointLocation", "hdfs:///checkpoints/logs-raw")
         .trigger(processingTime="20 seconds")
         .start())

이렇게 옮기면 오프셋은 컨슈머 그룹 대신 체크포인트에 남고, 이미 커밋된 배치를 다시 쓰는 일은 _spark_metadata가 거른다. 드라이버로 모아 쓰던 일은 executor가 파일을 직접 쓰는 일로 바뀌어 HDFS append가 필요 없다. 대신 배치마다 파티션마다 새 파일이 생기니 작은 파일은 오히려 늘 수 있어, 파일 합치는 잡은 계속 필요하다. 진행 위치도 체크포인트 디렉터리 하나에 모여서, 그 디렉터리를 잃으면 Kafka 쪽에 남은 위치가 없다. 예전 잡은 위치를 컨슈머 그룹에 두고 스트리밍을 단순하게 유지한 채, 겹친 줄은 뒤의 일 배치가 정리하는 쪽이었다.

참고 자료

English summary

DStream and Structured Streaming both run micro-batches, but they keep Kafka progress in different places. My DStream job left offsets to consumer auto commit and kept the streaming side simple, with a daily dropDuplicates() batch and a recovery mode on a separate consumer group handling overlaps and gaps. Structured Streaming does not commit to Kafka; it writes processed offset ranges to its checkpoint, and its file sink skips batches already logged in _spark_metadata. Moving that job over is a hypothetical here. It would put all progress in a checkpoint and a metadata log, which become the only record of where the job is, and which readers that list files directly, like Hive, do not see.

이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.