/ /

Change Stream으로 데이터 모니터링

개요

이 가이드 에서는 변경 스트림 을 사용하여 데이터의 실시간 변경 사항을 모니터 하는 방법을 학습 수 있습니다. 변경 스트림 은 애플리케이션 이 컬렉션, 데이터베이스 또는 배포서버 서버의 데이터 변경 사항을 구독 할 수 있도록 하는 MongoDB Server 기능 입니다.

MongoDB PHP 라이브러리를 사용할 watch() 때 메서드를 호출하여 인스턴스 MongoDB\ChangeStream 를 반환할 수 있습니다. 그런 다음 MongoDB\ChangeStream 인스턴스 를 반복하여 업데이트, 삽입 및 삭제와 같은 데이터 변경 사항을 모니터 할 수 있습니다.

팁

Atlas Stream Processing

변경 스트림의 대안으로 Atlas Stream Processing 사용하여 데이터 스트림을 프로세스 하고 변환할 수 있습니다. 데이터베이스 이벤트만 등록하는 변경 스트림과 달리 Atlas Stream Processing 여러 데이터 이벤트 유형을 관리하고 확장된 데이터 처리 기능을 제공합니다. 이 기능에 대해 자세히 학습하려면 MongoDB Atlas 설명서에서 Atlas Stream Processing 을 참조하세요.

샘플 데이터

The examples in this guide use the restaurants collection in the sample_restaurants database from the Atlas sample datasets. To access this collection from your PHP application, instantiate a MongoDB\Client that connects to an Atlas cluster and assign the following value to your $collection variable:

$collection = $client->sample_restaurants->restaurants;

팁

무료 MongoDB 배포서버 생성하고 샘플 데이터 세트를 로드하는 방법을 학습하려면, MongoDB 시작하기 가이드 참조하세요.

일부 예제에서는 toJSON() 함수를 사용하여 BSON 문서인 변경 이벤트를 확장 JSON 으로 표현합니다. 이 함수를 사용하려면 다음 코드를 애플리케이션 파일 에 붙여넣습니다.

function toJSON(object $document): string
{
    return MongoDB\BSON\Document::fromPHP($document)->toRelaxedExtendedJSON();
}

변경 스트림 열기

변경 스트림 을 열려면 watch() 메서드를 호출합니다. watch() 메서드를 호출하는 인스턴스 에 따라 변경 스트림 이 모니터링하는 이벤트 범위가 결정됩니다. 다음 클래스의 인스턴스에서 watch() 메서드를 호출할 수 있습니다.

MongoDB\Client: MongoDB deployment 의 모든 변경 사항을 모니터링합니다.
MongoDB\Database: 데이터베이스 내 모든 컬렉션의 변경 사항 모니터링
MongoDB\Collection: 컬렉션 의 변경 사항 모니터링

다음 예시에서는 restaurants 컬렉션에서 변경 스트림을 열고 변경 사항이 발생할 때 출력합니다.

$changeStream = $collection->watch();
$changeStream->rewind();
while (true) {
    $changeStream->next();
    if ($changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    echo toJSON($event), PHP_EOL;
    if ($changeStream->current()['operationType'] === 'invalidate') {
        break;
    }
}

변경 사항을 확인하려면 앞의 코드를 실행 하세요. 그런 다음 별도의 shell 에서 restaurants 컬렉션 을 수정합니다. 다음 예시 에서는 name 필드 값이 'Blarney Castle' 인 문서 를 업데이트합니다.

$result = $collection->updateOne(
    ['name' => 'Blarney Castle'],
    ['$set' => ['cuisine' => 'Irish']],
);

컬렉션 을 업데이트 하면 변경 스트림 애플리케이션 은 변경 사항이 발생하는 즉시 출력합니다. 인쇄된 변경 이벤트 는 다음 출력과 유사합니다.

{ "_id" : { "_data" : "..." }, "operationType" : "update", "clusterTime" :
{ "$timestamp" : { ... } }, "wallTime" : { "$date" : "..." }, "ns" : { "db" :
"sample_restaurants", "coll" : "restaurants" }, "documentKey" : { "_id" :
{ "$oid" : "..." } }, "updateDescription" : { "updatedFields" : { "cuisine" : "Irish" },
"removedFields" : [  ], "truncatedArrays" : [  ] } }

변경 스트림 출력 수정

변경 스트림 출력을 수정하려면 배열 의 파이프라인 단계를 watch() 메서드에 매개 변수로 전달하면 됩니다. 배열 에 다음 단계를 포함할 수 있습니다.

$addFields 또는 $set: 문서에 새 필드를 추가합니다.
$match: 문서를 필터링합니다.
$project: 문서 필드의 하위 집합을 프로젝션합니다.
$replaceWith 또는 $replaceRoot: 입력 문서 를 지정된 문서 로 바꿉니다.
$redact: 문서의 내용을 제한합니다.
$unset: 문서에서 필드를 제거합니다.

다음 예시 에서는 $match 단계가 포함된 파이프라인 을 watch() 메서드에 전달합니다. 이는 업데이트 작업이 발생할 때만 이벤트를 출력하도록 watch() 메서드에 지시합니다.

$pipeline = [['$match' => ['operationType' => 'update']]];
$changeStream = $collection->watch($pipeline);
$changeStream->rewind();
while (true) {
    $changeStream->next();
    if ($changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    echo toJSON($event), PHP_EOL;
    if ($changeStream->current()['operationType'] === 'invalidate') {
        break;
    }
}

팁

빌더와의 운영

빌더 패턴 사용하여 변경 스트림 파이프라인 생성할 수 있습니다. 자세한 학습 은 빌더를 사용한 작업 가이드 참조하세요.

`watch()` 동작 수정

watch() 메서드의 동작을 수정하려면 옵션 배열 을 watch() 에 매개 변수로 전달하면 됩니다. 다음 표에서는 배열 에서 설정하다 수 있는 유용한 옵션에 대해 설명합니다.

옵션	설명
`fullDocument`	문서 의 변경 사항만 표시하는 대신 변경 후 전체 문서 표시할지 여부를 지정합니다. 이 옵션에 대해 자세히 학습 이 가이드 의 사전 이미지 및 사후 이미지 포함 섹션을 참조하세요.
`fullDocumentBeforeChange`	Specifies whether to show the full document as it was before the change, rather than showing only the changes made to the document. To learn more about this option, see Include Pre-Images and Post-Images.
`startAfter`	다시 시작 토큰에 지정된 작업 후 `watch()` 에 새 변경 스트림 시작을 지시합니다. 이 필드를 통해 무효화 이벤트 후에 알림을 다시 시작할 수 있습니다. 각 변경 스트림 이벤트 문서에는 `_id` 필드로 이력서 토큰이 포함되어 있습니다. 이후에 재개하려는 작업을 나타내는 변경 이벤트 문서의 전체 `_id` 필드를 전달합니다. 이 옵션은 `resumeAfter` 과 `startAtOperationTime`와 상호 배타적입니다.
`startAtOperationTime`	변경 스트림에 지정된 타임스탬프 이후에 발생한 변경만 제공하도록 지시합니다. 이 옵션은 `startAfter` 과 `resumeAfter`에 상호 배타적입니다.
`collation`	변경 스트림 커서 에 사용할 데이터 정렬을 설정합니다. 자세히 학습 이 페이지의 데이터 정렬 섹션을 참조하세요.

watch() 옵션의 전체 목록은 API 문서에서 MongoDB \Collection::watch() 를 참조하세요.

사전 이미지 및 사후 이미지 포함하기

중요

배포에서 MongoDB v6.0 이상을 사용하는 경우에만 컬렉션에서 사전 이미지 및 사후 이미지를 활성화할 수 있습니다.

기본값 으로 컬렉션 에서 작업을 수행할 때 해당 변경 이벤트 에는 해당 작업에 의해 수정된 필드의 델타만 포함됩니다. 변경 전후의 전체 문서 를 보려면 배열 매개변수의 fullDocumentBeforeChange 또는 fullDocument 옵션을 watch() 로 지정합니다.

사전 이미지 는 변경 전의 문서 전체 버전입니다. 변경 스트림 이벤트 에 사전 이미지를 포함하려면 fullDocumentBeforeChange 옵션을 다음 값 중 하나로 설정하다 합니다.

MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_WHEN_AVAILABLE: 변경 이벤트 에는 변경 이벤트에 대한 수정된 문서 의 사전 이미지가 포함됩니다. 사전 이미지를 사용할 수 없는 경우 이 변경 이벤트 필드 의 값은 null 입니다.
MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_REQUIRED: 변경 이벤트 에는 변경 이벤트에 대한 수정된 문서 의 사전 이미지가 포함됩니다. 사전 이미지를 사용할 수 없는 경우 서버 에서 오류가 발생합니다.

사후 이미지 는 변경 후 문서 의 전체 버전입니다. 변경 스트림 이벤트 에 사후 이미지를 포함하려면 fullDocument 옵션을 다음 값 중 하나로 설정하다 합니다.

MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP: 변경 이벤트에는 변경 후 일정 시간 이후의 변경된 문서 전체의 복사본이 포함됩니다.
MongoDB\Operation\Watch::FULL_DOCUMENT_WHEN_AVAILABLE: 변경 이벤트 에는 변경 이벤트에 대한 수정된 문서 의 사후 이미지가 포함됩니다. 사후 이미지를 사용할 수 없는 경우 이 변경 이벤트 필드 의 값은 null 입니다.
MongoDB\Operation\Watch::FULL_DOCUMENT_REQUIRED: 변경 이벤트 에는 변경 이벤트에 대한 수정된 문서 의 사후 이미지가 포함됩니다. 사후 이미지를 사용할 수 없는 경우 서버 에서 오류가 발생합니다.

다음 예시 에서는 컬렉션 에서 watch() 메서드를 호출하고 fullDocument 옵션을 설정하여 업데이트된 문서의 사후 이미지를 포함합니다.

$options = ['fullDocument' => MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP];
$changeStream = $collection->watch([], $options);
$changeStream->rewind();
while (true) {
    $changeStream->next();
    if ($changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    echo toJSON($event), PHP_EOL;
    if ($changeStream->current()['operationType'] === 'invalidate') {
        break;
    }
}

변경 스트림 애플리케이션 이 별도의 shell 에서 실행 되는 경우 앞의 업데이트 예시 를 사용하여 restaurants 컬렉션 의 문서 를 업데이트하면 다음 출력과 유사한 변경 이벤트 가 출력됩니다.

{ "_id" : { "_data" : "..." }, "operationType" : "update", "clusterTime" :
{ "$timestamp" : { ... } }, "wallTime" : { "$date" : "..." },
"fullDocument" : { "_id" : { "$oid" : "..." }, "address" : { "building" :
"202-24", "coord" : [ -73.925044200000002093, 40.559546199999999772 ], "street"
: "Rockaway Point Boulevard", "zipcode" : "11697" }, "borough" : "Queens",
"cuisine" : "Irish", "grades" : [ ...], "name" : "Blarney Castle", "restaurant_id" :
"40366356" }, "ns" : { "db" : "sample_restaurants", "coll" : "restaurants" },
"documentKey" : { "_id" : { "$oid" : "..." } }, "updateDescription" :
{ "updatedFields" : { "cuisine" : "Irish" }, "removedFields" : [  ],
"truncatedArrays" : [  ] } }

팁

사전 이미지 및 사후 이미지에 대해 자세히 알아보려면 Change Streams 매뉴얼에서 문서 사전 및 사후 이미지로 MongoDB Server 을 참조하세요.

데이터 정렬

작업에 대한 데이터 정렬을 지정하려면 collation 옵션을 설정하는 $options 배열 매개변수를 작업 메서드에 전달합니다. 데이터 정렬 규칙을 구성하는 배열 에 collation 옵션을 할당합니다.

다음 표에서는 데이터 정렬을 구성하기 위해 설정하다 수 있는 필드에 대해 설명합니다.

필드	설명
`locale`	(Required) Specifies the International Components for Unicode (ICU) locale. For a list of supported locales, see Collation Locales and Default Parameters in the MongoDB Server manual. Data Type: `string`
`caseLevel`	(선택 사항) 대/소문자 비교 포함 여부를 지정합니다. 으로 `true`설정하면 비교 동작은 `strength` `strength` `1`필드의 값에 따라 달라집니다. - 가 인 경우 PHP 라이브러리는 기본 문자와 대/소문자를 비교합니다. - 가 `strength` `2`인 경우 PHP 라이브러리는 기본 문자, 양음 부호, 기타 세컨더리 차이 및 대/소문자를 비교합니다. - `strength` 이 다른 값인 경우 이 필드는 무시됩니다. `false`으로 설정하면 PHP 라이브러리는 강도 수준 `1` 또는 `2`에서 대/소문자 비교를 포함하지 않습니다. 데이터 유형: `bool` 기본값: `false`
`caseFirst`	(선택 사항) 3차 수준 비교 시 대소문자 차이의 정렬 순서를 지정합니다. 데이터 유형: `string` 기본값: `"off"`
`strength`	(Optional) Specifies the level of comparison to perform, as defined in the ICU documentation. Data Type: `int` Default: `3`
`numericOrdering`	(선택 사항) 운전자 숫자 문자열을 숫자로 비교할지 여부를 지정합니다. 로 설정하다 `true` 하면 PHP 라이브러리는 숫자 문자열을 숫자로 비교합니다. 예시 들어, "10" 및 "2"인 경우 라이브러리는 문자열의 숫자 값을 사용하고 "10" "2"보다 큽니다. 로 설정하다 `false` 하면 PHP 라이브러리는 숫자 문자열을 문자열로 비교합니다. 예시 를 들어 " " 및 & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & &10& & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & & &",2라이브러리는 한 번에 한 문자 한 자를 비교하고 & "10& "2"보다 작습니다. 자세한 내용은 MongoDB Server 매뉴얼에서 데이터 정렬 제한을 참조하세요. 데이터 유형: `bool` 기본값: `false`
`alternate`	(선택 사항) 비교를 위해 라이브러리에서 공백과 구듁점을 기본 문자로 간주할지 여부를 지정합니다. 데이터 유형: `string` 기본값: `"non-ignorable"`
`maxVariable`	(선택 사항) `alternate` 필드가 `"shifted"`(으)로 설정되어 있을 때 라이브러리가 무시할 수 있는 문자를 지정합니다. 데이터 유형: `string` 기본값: `"punct"`
`backwards`	(선택 사항) 분음 부호가 포함된 string이 string의 뒤쪽에서 앞쪽으로 정렬되는지 지정합니다. 데이터 유형: `bool` 기본값: `false`

데이터 정렬 및 각 필드에 사용할 수 있는 값에 대해 자세히 학습하려면 MongoDB Server 매뉴얼의 데이터 정렬 항목을 참조하세요.

추가 정보

변경 스트림에 대해 자세히 알아보려면 Change Streams 매뉴얼의 MongoDB Server 을 참조하세요.

API 문서

이 가이드에서 사용되는 메서드 또는 유형에 대해 자세히 알아보려면 다음 API 설명서를 참조하세요.

돌아가기

모니터링

로깅