애플리케이션 리셋 도구

애플리케이션 리셋 도구

개발하다 보면 "아, 처음부터 다시 처리하게 만들어야겠다" 싶을 때가 있어요. 버그를 고쳤거나 테스트 데이터를 다시 넣고 싶을 때요. 이럴 때 쓰는 게 바로 애플리케이션 리셋 도구(application reset tool)예요. 다만 이 도구는 되돌릴 수 없는 변경을 만들기 때문에, 이 페이지를 정독하고 꼭 --dry-run부터 써보시길 권해요.

출처: 문서

본문

애플리케이션 리셋 도구를 사용하면 애플리케이션을 리셋하고 처음부터 데이터를 다시 처리하도록 강제할 수 있어요. 이는 개발과 테스트, 또는 버그를 고칠 때 유용해요.

애플리케이션 리셋 도구는 리셋할 때 Kafka Streams 사용자 토픽(입력, 출력)과 내부 토픽을 다르게 처리해요. 각 토픽 유형에 대해 애플리케이션 리셋 도구가 하는 일은 다음과 같아요:

  • 입력 토픽: 오프셋을 지정된 위치로 리셋 (기본값은 토픽의 시작 부분).
  • 내부 토픽: 내부 토픽을 삭제 (이렇게 하면 커밋된 오프셋도 자동으로 삭제돼요).

애플리케이션 리셋 도구가 하지 않는 일:

  • 애플리케이션의 출력 토픽을 리셋하지 않아요. 어떤 출력 토픽이 다운스트림 애플리케이션에 의해 사용된다면, 업스트림 애플리케이션을 리셋할 때 해당 다운스트림 애플리케이션을 적절히 조정하는 것은 여러분의 책임이에요.
  • 애플리케이션 인스턴스의 로컬 환경을 리셋하지 않아요. 애플리케이션 인스턴스가 실행된 어떤 머신이든 로컬 상태를 삭제하는 것은 여러분의 책임이에요. 방법은 아래 "2단계: 애플리케이션 인스턴스의 로컬 환경 리셋" 섹션에 설명되어 있어요.

사전 요구사항

애플리케이션의 모든 인스턴스가 중지되어 있어야 해요. 그렇지 않으면 애플리케이션이 잘못된 상태에 들어가거나, 충돌하거나, 잘못된 결과를 만들 수 있어요. application.id를 ID로 하는 컨슈머 그룹이 여전히 활성 상태인지는 bin/kafka-consumer-groups로 확인할 수 있어요. 긴 세션 타임아웃(long session timeout)이 구성된 경우 활성 멤버가 브로커에서 만료되는 데 더 오래 걸려 리셋 작업이 완료되는 것을 막을 수 있어요. --force 옵션을 사용하면 남은 멤버를 즉시 제거할 수 있어요. 예상치 못한 리밸런스를 피하려면 이 옵션을 지정할 때 모든 스트림 애플리케이션을 종료했는지 확인하세요.

정보에 주의해서 사용하고 파라미터를 다시 확인하세요: 잘못된 파라미터 값(예: application.id의 오타)을 제공하거나 파라미터를 일관되지 않게 지정하면(예: 애플리케이션에 잘못된 입력 토픽을 지정), 이 도구가 애플리케이션의 상태를 무효화하거나 다른 애플리케이션, 컨슈머 그룹, 또는 여러분의 카프카 토픽에 영향을 줄 수 있어요.

1단계: 애플리케이션 리셋 도구 실행하기

  • 스트림즈 리밸런스 프로토콜(AK 4.2부터 사용 가능)을 사용한다면, Streams 그룹 CLI를 사용해요.
  • 클래식 리밸런스 프로토콜을 사용한다면, 아래에 설명된 대로 클래식 애플리케이션 리셋 도구를 실행해요.

명령줄에서 애플리케이션 리셋 도구 호출하기

경고! 이 도구는 애플리케이션에 되돌릴 수 없는 변경을 만들어요. 변경하기 전에 미리보기하려면 --dry-run으로 한 번 실행하는 것을 강력히 권장해요.

$ bin/kafka-streams-application-reset.sh

도구는 다음 파라미터를 받아요:

Option (* = required)                 Description
---------------------                 -----------
* --application-id <String: id>       REQUIRED: The Kafka Streams application ID
                                        (application.id).
--bootstrap-server <String: server to  The server(s) to connect to.
                           connect to>  The broker list string in the form HOST1:PORT1,HOST2:PORT2.
                                        (default: localhost:9092)
--by-duration <String: urls>          Reset offsets to offset by duration from
                                        current timestamp. Format: 'PnDTnHnMnS'
--config-file <String: file name>     (Deprecated) Property file containing configs to be
                                        passed to admin clients and embedded consumer.
                                        This option will be removed in a future version.
                                        Use --command-config instead.
--command-config <String: file name>  Config properties file to be passed to admin clients
                                        and embedded consumer.
--dry-run                             Display the actions that would be
                                        performed without executing the reset
                                        commands.
--from-file <String: urls>            Reset offsets to values defined in CSV
                                        file.
--input-topics <String: list>         Comma-separated list of user input
                                        topics. For these topics, the tool will
                                        reset the offset to the earliest
                                        available offset.
--internal-topics <String: list>      Comma-separated list of internal topics
                                        to delete. Must be a subset of the
                                        internal topics marked for deletion by
                                        the default behaviour (do a dry-run without
                                        this option to view these topics).
--shift-by <Long: number-of-offsets>  Reset offsets shifting current offset by
                                        'n', where 'n' can be positive or
                                        negative
--to-datetime <String>                Reset offsets to offset from datetime.
                                        Format: 'YYYY-MM-DDThh:mm:ss.sss'
--to-earliest                         Reset offsets to earliest offset.
--to-latest                           Reset offsets to latest offset.
--to-offset <Long>                    Reset offsets to a specific offset.
--force                               Force removing members of the consumer group
                                      (intended to remove left-over members if
                                      long session timeout was configured).

input-topics에 대한 오프셋 리셋 시나리오를 다음과 같이 고려해요:

  • by-duration
  • from-file
  • shift-by
  • to-datetime
  • to-earliest
  • to-latest
  • to-offset

이 시나리오 중 하나만 정의할 수 있어요. 지정하지 않으면 기본적으로 to-earliest가 실행돼요. 다른 모든 파라미터는 필요에 따라 조합할 수 있어요. 예를 들어, 빈 내부 상태에서 애플리케이션을 재시작하고 싶지만 이전 데이터를 다시 처리하고 싶지는 않다면, --input-topics 파라미터를 생략하면 돼요.

2단계: 애플리케이션 인스턴스의 로컬 환경 리셋

완전한 애플리케이션 리셋을 위해서는 애플리케이션 인스턴스가 실행된 어떤 머신이든 애플리케이션의 로컬 상태 디렉터리를 삭제해야 해요. 같은 머신에서 애플리케이션 인스턴스를 재시작하기 전에 이 작업을 해야 돼요. 다음 두 가지 방법 중 하나를 사용할 수 있어요:

  • 애플리케이션 코드에서 API 메서드 KafkaStreams#cleanUp()을 사용.
  • 해당 로컬 상태 디렉터리를 수동으로 삭제 (기본 위치: /${java.io.tmpdir}/kafka-streams/<application.id>). 자세한 내용은 Streams javadocs를 참고해요.

더 알아보기