STREAM BACKLOG
SAFE OPERATING BOUNDARY
consumer code·설정·instance 변경은 이전 정상 release로 되돌립니다. offset 변경은 0600으로 보관한 current-offsets.csv를 대상으로 group을 완전히 멈추고 dry-run 결과와 중복 처리 범위를 다시 승인한 뒤에만 복원합니다. 이미 처리한 외부 side effect와 건너뛴 message는 offset만 되돌려 복원되지 않으므로 idempotency key·재처리·업무 보정 절차가 필요합니다.
BEFORE YOU START
CHECK THE BRANCH
producer 유입 급증과 consumer의 정상 처리 용량 차이입니다. partition 수·member 수·처리 비용·downstream 한계를 함께 계산하고 무조건 instance만 늘리지 않습니다.
처리 시간이 max.poll.interval.ms를 넘거나 heartbeat·network·GC pause·배포 불안정으로 rebalance가 반복될 수 있습니다. timeout만 늘려 처리 정지를 숨기지 않습니다.
hot key·partition skew, 해당 leader broker·disk·network 문제 또는 poison message를 확인합니다. consumer 수가 partition 수를 넘으면 추가 instance는 처리량을 늘리지 못합니다.
group을 완전히 비활성화하고 현재 offset을 export한 뒤 dry-run 결과와 업무 중복·유실 범위를 승인해야 합니다. latest 이동은 미처리 메시지를 건너뛸 수 있습니다.
FOLLOW THE FLOW
인증정보는 0600 command config 파일로 전달하고 명령행에 password를 넣지 않습니다. 장애 시각의 offset과 active member를 같은 시점에 기록합니다.
stat -Lc '%a %U:%G %n' <KAFKA_COMMAND_CONFIG><KAFKA_HOME>/bin/kafka-consumer-groups.sh --bootstrap-server <BOOTSTRAP_SERVERS> --command-config <KAFKA_COMMAND_CONFIG> --describe --group <CONSUMER_GROUP><KAFKA_HOME>/bin/kafka-consumer-groups.sh --bootstrap-server <BOOTSTRAP_SERVERS> --command-config <KAFKA_COMMAND_CONFIG> --describe --group <CONSUMER_GROUP> --state<KAFKA_HOME>/bin/kafka-consumer-groups.sh --bootstrap-server <BOOTSTRAP_SERVERS> --command-config <KAFKA_COMMAND_CONFIG> --describe --group <CONSUMER_GROUP> --members --verboseLAG는 partition별 LOG-END-OFFSET과 CURRENT-OFFSET 차이이며 단일 순간값보다 증가율이 중요합니다. member 수·assignment·state와 함께 봅니다.
lag가 집중된 topic·partition의 leader와 topic 구성을 확인합니다.
topic partition 수, leader·ISR와 hot partition을 비교합니다. 전체 cluster metadata를 외부로 공유하지 않습니다.
<KAFKA_HOME>/bin/kafka-topics.sh --bootstrap-server <BOOTSTRAP_SERVERS> --command-config <KAFKA_COMMAND_CONFIG> --describe --topic <TOPIC><KAFKA_HOME>/bin/kafka-consumer-groups.sh --bootstrap-server <BOOTSTRAP_SERVERS> --command-config <KAFKA_COMMAND_CONFIG> --describe --group <CONSUMER_GROUP> --offsets<KAFKA_HOME>/bin/kafka-broker-api-versions.sh --bootstrap-server <BOOTSTRAP_SERVERS> --command-config <KAFKA_COMMAND_CONFIG>leader·ISR 이상과 같은 partition lag가 일치하면 broker·replication 문제를 먼저 해결합니다. 모든 partition lag가 비슷하면 consumer 처리 용량·downstream을 우선 봅니다.
consumer 로그·GC·처리 시간·downstream latency를 확인합니다.
애플리케이션 로그와 metrics에서 poll, processing, commit, rebalance, error와 downstream 지연을 확인합니다. message payload는 수집하지 않습니다.
systemctl status <CONSUMER_SERVICE>.service --no-pager -l
systemctl show <CONSUMER_SERVICE>.service -p MainPID -p NRestarts -p MemoryCurrent -p MemoryPeakjournalctl -u <CONSUMER_SERVICE>.service --since '<INCIDENT_START>' --until '<INCIDENT_END>' --no-pager | grep -Ei -C 4 'rebalance|max.poll|commit|offset|timeout|exception|error'free -h
cat /proc/pressure/cpu
cat /proc/pressure/memory
cat /proc/pressure/iocurl -fsS --connect-timeout 3 <APPROVED_DOWNSTREAM_HEALTH_URL>poll loop 정지·GC pause·처리 시간 증가·commit 실패·downstream 포화를 lag 증가 시각과 비교합니다. rebalance 횟수만으로 원인을 단정하지 않습니다.
consumer 설정과 partition·instance·업무 idempotency 경계를 검토합니다.
group.id, subscription, assignor, poll·session timeout, auto commit, instance 수를 source control에서 검토합니다. offset reset은 group 비활성·export·dry-run·업무 승인 없이는 금지합니다.
git -C <CONSUMER_REPOSITORY> diff <LAST_GOOD_REVISION> -- <CONSUMER_CONFIG_PATH>install -d -m 0700 <APPROVED_BACKUP_DIR>
umask 077
<KAFKA_HOME>/bin/kafka-consumer-groups.sh --bootstrap-server <BOOTSTRAP_SERVERS> --command-config <KAFKA_COMMAND_CONFIG> --reset-offsets --group <CONSUMER_GROUP> --all-topics --to-current --export > <APPROVED_BACKUP_DIR>/current-offsets.csv
chmod 0600 <APPROVED_BACKUP_DIR>/current-offsets.csv<KAFKA_HOME>/bin/kafka-consumer-groups.sh --bootstrap-server <BOOTSTRAP_SERVERS> --command-config <KAFKA_COMMAND_CONFIG> --reset-offsets --group <CONSUMER_GROUP> --from-file <REVIEWED_OFFSET_PLAN.csv> --dry-runconsumer scaling은 partition 수와 downstream 여유까지만 효과가 있습니다. offset 이동은 처리량 문제가 아니라 위치 변경이며 데이터 중복·유실을 일으킬 수 있습니다.
코드·용량·downstream 복구 또는 승인된 offset 계획 중 원인에 맞는 하나를 선택합니다.
일반 장애는 검증된 consumer release·instance 수·설정을 배포합니다. offset reset은 group inactive, 0600 export, dry-run, 업무 보정 계획을 모두 충족한 별도 분기에서만 실행합니다.
sudo systemctl restart <CONSUMER_SERVICE>.service
systemctl status <CONSUMER_SERVICE>.service --no-pager -l<KAFKA_HOME>/bin/kafka-consumer-groups.sh --bootstrap-server <BOOTSTRAP_SERVERS> --command-config <KAFKA_COMMAND_CONFIG> --reset-offsets --group <CONSUMER_GROUP> --from-file <REVIEWED_OFFSET_PLAN.csv> --execute<KAFKA_HOME>/bin/kafka-consumer-groups.sh --bootstrap-server <BOOTSTRAP_SERVERS> --command-config <KAFKA_COMMAND_CONFIG> --describe --group <CONSUMER_GROUP>
<KAFKA_HOME>/bin/kafka-consumer-groups.sh --bootstrap-server <BOOTSTRAP_SERVERS> --command-config <KAFKA_COMMAND_CONFIG> --describe --group <CONSUMER_GROUP> --members --verbosesystemctl show <CONSUMER_SERVICE>.service -p NRestarts -p ExecMainStatus
curl -fsS <APPROVED_CONSUMER_HEALTH_URL>lag 증가율이 음수로 전환되고 rebalance·commit error가 안정화되며 downstream과 업무 처리 정확성이 유지돼야 합니다. 단순 lag 0만으로 성공을 판단하지 않습니다.
코드·설정은 이전 release로 되돌립니다. offset은 0600 current-offsets.csv를 from-file로 dry-run하고 group inactive·업무 승인 뒤에만 복원하며, 이미 처리·건너뛴 message는 자동으로 원복되지 않으므로 idempotency와 보정 작업을 적용합니다.
PRIMARY REFERENCES
배포판과 버전에 따라 옵션·로그 위치가 다를 수 있습니다. 실행 전 서버의 --help와 로컬 매뉴얼을 함께 확인하세요.