donghyeon.kang/llm-wiki

Fork 0

Files

T

DongHyeonka 58515ab0f3 feat: 공식 문서 근거자료, 브랜치 기능 문서 작성

2026-07-29 18:05:17 +09:00

12 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title

source_type

url

archive_url

related_branches

related_projects

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 스키마)

12 KiB Raw Permalink Blame History