llm-wiki/raw/official-docs/change-streams-mongodb-official.md

---
title: official-doc / MongoDB Change Streams — Availability, Resume Tokens, Invalidate Events
source_type: official-doc
url: https://www.mongodb.com/docs/manual/changeStreams/
archive_url:
related_branches: [feature-mongo-runtime-baseline-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, persistence, mongodb, change-stream]
created: 2026-07-28
---

# MongoDB Change Streams — Availability, Resume Tokens, Invalidate Events

> Layer: `raw/` — 외부 자료(공식 문서 / 대기업 기술 블로그)의 **원문 발췌·출처 기록**.
> 본 템플릿은 `raw/official-docs/` 와 `raw/company-tech-blogs/` 두 폴더가 공유.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.

## source_type 허용값

- `official-doc` — MongoDB 공식 Database Manual (Server 8.3 current)

## 활용 branch (필수, 최소 1개+)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-mongo-runtime-baseline-contract]] | "change stream 은 replica set / sharded cluster 요건 검증을 통과할 때만 활성화하고, resume token 을 checkpoint 저장소에 영속화하며, oplog window 를 감시한다" 결정의 근거 |

## 출처

- 원본 URL: https://www.mongodb.com/docs/manual/changeStreams/
- 아카이브 URL: (미등록)
- 저자 / 조직: MongoDB, Inc. (공식 Database Manual)
- 발행일: 확인 불가 (지속 갱신 레퍼런스 문서, 페이지 상단 버전 표기: Database Manual 8.3 (Current))
- 마지막 확인일: 2026-07-28

## 왜 저장했는지

`feature-mongo-runtime-baseline-contract` 브랜치가 change stream 활성화 조건(배포 형태·storage engine·read concern majority 요건), resume token 기반 checkpoint 설계(resumeAfter/startAfter/startAtOperationTime), oplog window 부족 시 resume 실패, invalidate event 로 인한 stream 종료 조건을 결정하기 위한 1차 공식 근거.

## 핵심 인용

> [§Availability] "Change streams are available for replica sets and sharded clusters"

> [§Availability — Storage Engine] "The replica sets and sharded clusters must use the WiredTiger storage engine."

> [§Availability — Read Concern "majority" Enablement] "Change streams are available regardless of the "majority" read concern support; that is, read concern majority support can be either enabled (default) or disabled to use change streams."

> [§Resume a Change Stream — resumeAfter] "You can resume a change stream after a specific event by passing a resume token to resumeAfter when opening the cursor."

> [§Resume a Change Stream — startAfter] "Unlike resumeAfter , startAfter can resume notifications after an invalidate event by creating a new change stream."

> [§Open a Change Stream — startAtOperationTime] "You can specify a startAtOperationTime to open the cursor at a particular point in time. If the specified starting point is in the past, it must be in the time range of the oplog."

> [§resumeAfter for Change Streams / startAfter for Change Streams — Important note (oplog window)] "The oplog must have enough history to locate the operation associated with the token or the timestamp, if the timestamp is in the past."

> [§Open a Change Stream — cursor lifecycle] "The cursor is explicitly closed." / "An invalidate event occurs; for example, a collection drop or rename." / "The connection to the MongoDB deployment closes or times out." / "If the deployment is a sharded cluster, a shard removal may cause an open change stream cursor to close."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| MONGO-CHANGESTREAM-C1 | Change stream 은 replica set 또는 sharded cluster 배포에서만 사용 가능하며, standalone 배포는 지원하지 않는다 | [§Availability] "Change streams are available for replica sets and sharded clusters" | `official-vendor-doc` | 배포 형태 사전 검증 로직 (standalone 배포에서 change stream 활성화 시도를 거부해야 함) | ca-tmpl/ca-skeleton 의 실제 배포 토폴로지에서 이 검증이 어떻게 구현되어야 하는지는 증명하지 않음 |
| MONGO-CHANGESTREAM-C2 | Change stream 을 사용하는 replica set/sharded cluster 는 WiredTiger storage engine 을 사용해야 한다 | [§Availability — Storage Engine] "The replica sets and sharded clusters must use the WiredTiger storage engine." | `official-vendor-doc` | storage engine 사전 조건 검증 | 다른 storage engine(MMAPv1 등) 환경에서의 대체 동작은 다루지 않음 |
| MONGO-CHANGESTREAM-C3 | Change stream 사용에 `"majority"` read concern 지원 활성화 여부는 무관하다 (활성화/비활성화 모두 가능) | [§Read Concern "majority" Enablement] "Change streams are available regardless of the "majority" read concern support; that is, read concern majority support can be either enabled (default) or disabled to use change streams." | `official-vendor-doc` | change stream 자체의 가용 조건 판단 | change stream 이 반환하는 이벤트의 durability/일관성 보장 수준 자체를 설명하지 않음 — read concern majority 가 비활성화된 상태에서 change stream 이 반환하는 이벤트가 이후 rollback 될 수 있는지는 이 문장만으로 증명 불가 (별도 확인 필요) |
| MONGO-CHANGESTREAM-C4 | `resumeAfter` 는 resume token 을 지정해 특정 이벤트 이후부터 change stream 을 재개하는 옵션이다 | [§resumeAfter for Change Streams] "You can resume a change stream after a specific event by passing a resume token to resumeAfter when opening the cursor." | `official-vendor-doc` | checkpoint 저장소에서 읽은 resume token 으로 정상 재개하는 경로 설계 | invalidate event 이후에도 동작하는지는 이 claim 만으로 보장되지 않음 (C5 참조) |
| MONGO-CHANGESTREAM-C5 | `resumeAfter` 와 달리 `startAfter` 는 invalidate event 이후에도 새 change stream 을 시작해 알림을 재개할 수 있다 | [§startAfter for Change Streams] "Unlike resumeAfter , startAfter can resume notifications after an invalidate event by creating a new change stream." | `official-vendor-doc` | invalidate event(컬렉션 drop/rename 등) 발생 후 checkpoint 기반 재개 전략 분기 | `resumeAfter` 로 invalidate event 이후 재개를 시도했을 때의 정확한 에러 형태까지는 이 문장만으로 명시되지 않음 |
| MONGO-CHANGESTREAM-C6 | `startAtOperationTime` 은 특정 시점부터 커서를 여는 옵션이며, 과거 시점을 지정하면 그 시점이 oplog 의 시간 범위 안에 있어야 한다 | [§Open a Change Stream] "You can specify a startAtOperationTime to open the cursor at a particular point in time. If the specified starting point is in the past, it must be in the time range of the oplog." | `official-vendor-doc` | 최초 checkpoint 가 없는 상태에서 특정 시점부터 change stream 을 시작하는 경로 | timestamp 가 oplog 범위를 벗어났을 때의 정확한 실패 메시지/예외 타입은 명시하지 않음 |
| MONGO-CHANGESTREAM-C7 | resume token 또는 timestamp 로 지정된 operation 을 찾으려면 oplog 가 충분한 history 를 보유하고 있어야 하며, 그렇지 못하면 resume 이 불가능하다 (oplog window 요구) | [§resumeAfter/startAfter for Change Streams — Important] "The oplog must have enough history to locate the operation associated with the token or the timestamp, if the timestamp is in the past." | `official-vendor-doc` | oplog window 감시 알람 설계, checkpoint 지연이 oplog retention 을 초과하지 않도록 하는 운영 기준 근거 | 구체적인 oplog 크기 산정 공식이나 권장 retention 시간(초/일 단위)은 이 문장에 없음 — 별도 Production Recommendations 페이지 확인 필요 (`needs-confirmation`) |
| MONGO-CHANGESTREAM-C8 | change stream cursor 는 (a) 명시적 종료, (b) invalidate event(예: 컬렉션 drop 또는 rename) 발생, (c) MongoDB 배포와의 연결 종료/타임아웃, (d) sharded cluster 에서 shard 제거 중 하나가 발생하면 닫힌다 | [§Open a Change Stream] "The cursor is explicitly closed." / "An invalidate event occurs; for example, a collection drop or rename." / "The connection to the MongoDB deployment closes or times out." / "If the deployment is a sharded cluster, a shard removal may cause an open change stream cursor to close." | `official-vendor-doc` | invalidate event 발생 시 stream 종료를 감지하고 checkpoint 재개 전략(`startAfter`)으로 분기하는 에러 핸들링 설계 | 각 종료 사유를 애플리케이션 코드에서 어떻게 구분해 감지하는지(드라이버별 API)는 이 문장에 없음 |

### Strength 허용값

- `official-standard` — RFC, 표준 사양, 언어/프로토콜 표준
- `official-vendor-doc` — Spring, Keycloak, AWS, Google 등 공식 벤더 문서
- `official-reference` — 공식 reference/API 문서
- `company-case-study` — 대기업/실무 기술 블로그의 특정 사례
- `engineering-blog` — 개인/팀 블로그의 엔지니어링 해설
- `tutorial` — 튜토리얼/가이드. 일반화 금지
- `needs-confirmation` — 원문만으로는 적용 판단 불가

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `MONGO-CHANGESTREAM-C1`: change stream 은 replica set/sharded cluster 배포에서만 사용 가능하다 (standalone 불가)
  - `MONGO-CHANGESTREAM-C2`: WiredTiger storage engine 이 필요하다
  - `MONGO-CHANGESTREAM-C3`: read concern majority 지원 활성화 여부와 무관하게 change stream 사용 가능하다
  - `MONGO-CHANGESTREAM-C4`~`C6`: resumeAfter/startAfter/startAtOperationTime 세 옵션의 역할과 각각의 적용 조건
  - `MONGO-CHANGESTREAM-C7`: oplog 가 resume token/timestamp 에 해당하는 이벤트를 이미 롤오버(삭제)했다면 resume 이 실패한다 (oplog window 요구)
  - `MONGO-CHANGESTREAM-C8`: invalidate event 를 포함한 4가지 조건에서 change stream cursor 가 닫힌다
- 이 자료가 증명하지 않는 것:
  - 구체적인 oplog 크기 산정 공식이나 권장 retention 시간 (별도 Production Recommendations 페이지 영역)
  - resume token 을 애플리케이션 checkpoint 저장소(DB 테이블 등)에 영속화하는 구체적 구현 패턴 — 이는 원문에 없는 ca-tmpl/ca-skeleton 측 설계 결정
  - `resumeAfter` 실패 시 정확한 예외 타입/에러 코드 (드라이버별 상이할 수 있음)
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-skeleton 이 실제로 배포할 MongoDB 토폴로지(replica set 최소 멤버 수, WiredTiger 기본 여부)가 이 요건을 만족하는지 로컬/dev 환경에서 검증 필요
  - oplog window 감시 알람의 구체적 임계값(예: checkpoint 지연이 oplog 예상 소진 시간의 몇 %를 넘으면 경보)은 이 자료에 없으므로 별도 설계 필요

## 메모

- oplog window 요구(`MONGO-CHANGESTREAM-C7`)는 정성적 서술("must have enough history")만 있고 정량 기준이 없다. Production Recommendations 페이지(원문에서 "Back Limitations Next Production Recommendations" 로 다음 페이지 링크됨)를 별도 raw 자료로 추가 수집할 필요가 있는지는 `/branch-spec` 단계에서 판단.
- 추가로 봐야 할 동일 출처 페이지: `Production Recommendations`, `Change Stream Events` (invalidate 이벤트의 정확한 document 스키마)

## 관련

- 같은 주제 다른 official-doc: [[raw/official-docs/write-concern-mongodb-official]], [[raw/official-docs/read-preference-mongodb-official]] (동일 벤더, 인접 결정 영역)
- 이 자료를 인용한 wiki 요약: (아직 생성되지 않음)