[Cloudflare Queues][운영] tail-message incident field를 남긴 뒤 replay batch disposition과 ack scope를 어떤 표로 같이 고정하나

IT 리서치 노트

[Cloudflare Queues][운영] tail-message incident field를 남긴 뒤 replay batch disposition과 ack scope를 어떤 표로 같이 고정하나

Cloudflare Queues에서 tail-message incident field까지는 잘 남겼는데, 그다음 DLQ replay 직전 판단이 다시 애매해지는 경우가 있다. 2026년 8월 30일 KST 기준 Cloudflare 공식 문서를 다시 보면 batch 실패, explicit ack, retry limit, pull consumer ack 범위는 서로 다른 층위다. 이 글은 tail-message incident field를 이미 정리한 뒤 replay batch disposition과 ack scope를 어떤 표로 같이 고정해야 후속 복구가 덜 꼬이는지 정리한다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 replay 직전에는 tail-message incident field만으로 부족하고, ack scope와 batch disposition를 같은 메모에 붙여야 한다. 메시지 하나의 원인과 batch 전체 처리 결정을 따로 쓰지 않으면 explicit ack를 했는지, replay에서 제외해야 할 메시지가 무엇인지, retry limit 직전인지가 다시 섞인다. 운영자는 replay 전에 로그를 확인하고, queue 설정을 조회하고, 실패 응답을 저장하고, ack 범위를 다시 확인해야 한다.

같은 Cloudflare 가지에서 delayed retry cohort와 lease renew·ack gap을 분리한 글이 원인 층을 다뤘고, tail-message incident field 글이 replay 전 메모 층을 다뤘다면, 이번 글은 그 위에 disposition 결정을 얹는 후속편이다.

2. 어디서 실제로 막히는가

현장에서 자주 꼬이는 지점은 세 가지다. 첫째, tail message의 원인은 적었는데 batch 안에서 어떤 메시지를 이미 ack 했는지 안 남긴다. 둘째, retry limit에 닿은 메시지와 아직 queue에서 retry 가능한 메시지를 같은 replay 후보로 묶는다. 셋째, pull consumer에서 일부 메시지만 재시도해야 하는데 batch 전체를 다시 돌려 duplicate write를 만든다.

Cloudflare 문서는 explicit ack가 없는 경우 batch 실패가 전체 재전달로 이어질 수 있다고 설명한다. 또 DLQ 문서는 retry limit에 도달한 메시지만 DLQ로 이동한다고 적고, pull consumer 문서는 pull과 ack를 직접 제어한다고 안내한다. 이 세 문장을 합치면, replay 전 결정은 원인 기록과 처리 범위가 분리되어야 한다는 결론이 나온다.

문제는 많은 팀이 replay를 누를지 말지만 적고, replay 범위와 이미 ack된 메시지를 기록하지 않는다는 점이다. 그러면 같은 incident가 끝난 뒤에도 왜 duplicate read가 있었는지, 왜 어떤 write는 두 번 반영됐는지, 왜 특정 batch만 제외됐는지 설명이 안 남는다. 특히 콘솔 로그를 조회하지 않거나, failed position 응답을 저장하지 않거나, replay 전 queue 설정을 다시 확인하지 않으면 같은 오류가 반복된다.

• 증상: replay 뒤 duplicate write 또는 duplicate read가 다시 생긴다.
• 실패: tail-message 원인만 남기고 ack scope를 기록하지 않는다.
• 막힘: retry 가능 메시지와 DLQ replay 후보를 같은 줄에 적는다.
• 누락: batch 단위 decision과 message 단위 decision을 나누지 않는다.

겉으로 보이는 현상	실제로 다시 볼 값	판단 기준
replay 뒤 동일 write가 반복된다	ack scope, idempotency key	이미 ack된 메시지를 재대상에 넣었는지 본다
어떤 batch만 계속 tail로 남는다	failed position, lease state	batch 전체 문제인지 일부 메시지 문제인지 나눈다
DLQ replay 범위가 설명되지 않는다	batch disposition	retry-in-queue, hold, replay-candidate를 따로 본다

3. 실무에서 적용하는 순서

가장 실용적인 순서는 다섯 단계다. 먼저 graph window와 oldest age를 고정해 queue-wide 회복과 tail-only 문제를 분리한다. 다음으로 tail batch의 failed position과 retryCount를 적는다. 세 번째로 이미 ack된 메시지 범위를 message-level인지 batch-level인지 표시한다. 네 번째로 disposition을 retry-in-queue, investigate-first, dlq-replay-candidate 중 하나로 고정한다. 마지막으로 그 뒤에만 replay owner와 실행 조건을 적는다. 이때 운영자는 콘솔에서 로그를 조회하고, API 응답을 확인하고, 실행 명령과 결과 파일을 저장하는 흐름을 같이 남겨야 한다.

1. queue-wide 지표와 tail 지표를 먼저 분리한다.
2. failed position과 retryCount를 적는다.
3. ack scope를 message-level 또는 batch-level로 고정한다.
4. batch disposition을 세 가지 중 하나로 정한다.
5. 그 다음에만 replay owner와 실행 조건을 기록한다.

실행 전에 할 일도 분명하다. 운영 콘솔에서 oldest age 로그를 조회하고, 관련 메시지 응답을 복사해 incident 파일에 저장하고, queue 설정과 consumer 설정을 다시 확인하고, replay 실행 명령을 별도 줄로 남긴다. 이 네 동작을 빠뜨리면 나중에 왜 그 batch를 다시 실행했는지 설명이 약해진다.

replay 직전 운영 메모

queue_window=15m
tail_message_id=msg_001
failed_position=7
ack_scope=message-level
batch_disposition=dlq-replay-candidate
replay_owner=queue-ops
execute_after=lease_state_rechecked

이 순서가 좋은 이유는 replay가 원인 분석의 대체물이 되지 않기 때문이다. tail-message incident field가 이미 post 436에서 원인을 좁혔다면, 이번 표는 그 원인을 실제 batch 실행으로 옮길지, 더 조사할지, queue 안에서 retry로 둘지 결정하는 단계다.

4. 공식 문서와 예시 화면으로 확인하기

첫 자료는 Cloudflare Queues batching 문서의 핵심 문장이다. 한 메시지가 실패하면 explicit ack를 하지 않은 나머지 메시지까지 같은 batch가 다시 전달될 수 있다는 전제를 먼저 봐야 한다.

Cloudflare는 explicit ack가 없으면 batch 실패가 전체 재전달로 이어질 수 있다고 설명한다.

즉 replay 직전 메모에서 메시지 단위 원인만 적어 두면 부족하다. 어떤 batch를 어느 범위까지 ack 했는지와 나머지를 어떤 disposition으로 남길지 따로 적어야 duplicate read와 duplicate write를 다시 줄일 수 있다.

두 번째 자료는 DLQ 문서다. Cloudflare는 retry limit에 도달한 메시지만 DLQ로 이동한다고 분명히 적고 있다.

DLQ는 단순 백업 보관함이 아니라 retry limit 이후 경로다.

따라서 DLQ replay는 첫 반응이 아니라 retry 경계 이후 조치다. tail-message incident field를 이미 적었다면, 그 다음은 replay 후보 batch의 disposition과 ack scope를 함께 고정하는 단계다.

세 번째 자료는 pull consumer 문서다. pull consumer는 읽기와 ack가 자동이 아니므로, replay 후속 메모도 개별 ack 범위 기준으로 써야 한다.

pull consumer에서는 pull, ack, retry 범위를 명시적으로 남겨야 replay 기준이 분명해진다.

여기서 중요한 것은 batch 전체를 성공처럼 적지 않는 일이다. 동일 batch 안에서도 일부 메시지는 ack, 일부는 retry, 일부는 DLQ replay 후보로 남을 수 있으니 ack scope와 disposition을 분리해야 한다.

실무에서는 replay 전에 표 한 장으로 정리하는 편이 가장 빠르다. 아래 표는 tail-message incident field 다음에 바로 붙여 두면 좋은 disposition 기준이다.

tail field 이후에는 batch disposition과 ack scope를 같은 표로 적는 편이 빠르다.

이미 tail-message incident field 글을 원인 메모로 봤다면, 이번 표는 DLQ replay 체크리스트 글로 넘어가기 직전의 운영 결정표다.

마지막 자료는 실제 메모 예시다. 핵심은 batch disposition, ack scope, replay 후보 여부를 같은 객체 안에 두는 것이다.

replay 메모는 tail field와 disposition을 한 레코드에 같이 남겨야 한다.

이렇게 남겨 두면 post 364의 delayed retry versus lease gap 판단, post 436의 tail-message 메모, 그리고 실제 replay 실행 전 판단이 한 줄로 이어진다.

5. 주의사항과 리스크

첫 번째 리스크는 원인 메모는 남겼지만 batch disposition을 안 적는 것이다. 두 번째는 message-level ack를 해 놓고 batch-level replay처럼 운영하는 것이다. 세 번째는 retry 가능 메시지와 이미 DLQ로 이동한 메시지를 같은 조치로 묶는 것이다.

운영 전에 최소한 failed position, ack scope, batch disposition, replay owner 네 칸은 고정해 두는 편이 좋다. 이 네 칸이 없으면 replay 후 duplicate나 재처리 누락을 설명하기 어렵다.

• tail field만으로 replay 결정을 대신하지 않는다.
• ack scope와 batch disposition을 항상 분리한다.
• DLQ replay 후보와 queue 내 retry 후보를 같은 줄에 두지 않는다.

6. 결론

Cloudflare Queues에서 tail-message incident field를 정리한 뒤에는 replay batch disposition과 ack scope를 같은 표로 고정해야 한다. 그래야 explicit ack 경계, DLQ retry limit, pull consumer 제어 범위를 실제 복구 절차로 옮길 수 있다.

같은 분기의 다음 읽을 거리로는 tail-message incident field 글과 DLQ replay 체크리스트 글을 이어서 보면 replay 전 메모와 실제 실행 순서가 끊기지 않는다.

7. 참고 링크

1. https://developers.cloudflare.com/queues/configuration/batching-retries/
2. https://developers.cloudflare.com/queues/configuration/dead-letter-queues/
3. https://developers.cloudflare.com/queues/configuration/pull-consumers/
4. https://developers.cloudflare.com/queues/examples/list-messages-from-dash/