이벤트 전달 의미론
이 페이지에서는 Currents가 데이터 웨어하우스 스토리지 파트너에게 보내는 플랫 파일 이벤트 데이터를 관리하는 방법을 간략하게 설명하고 정의합니다.
데이터 스토리지용 Currents는 플랫폼에서 데이터 웨어하우스 파트너 연결 중 하나에 있는 스토리지 버킷으로 데이터를 지속적으로 스트리밍하는 것입니다. Currents는 일정한 임계값에 따라 Avro 파일을 스토리지 버킷에 기록하여 자체 비즈니스 인텔리전스(BI) 도구 세트로 이벤트 데이터를 처리하고 분석할 수 있도록 합니다.
이 콘텐츠는 데이터 웨어하우스 스토리지 파트너(Google Cloud Storage, Amazon S3, Microsoft Azure Blob Storage)로 전송하는 플랫 파일 이벤트 데이터에만 적용됩니다.
다른 파트너에게 적용되는 콘텐츠는 사용 가능한 파트너 목록을 참조하여 해당 페이지를 확인하세요.
테스트 이벤트
Currents 통합을 설정할 때 테스트 이벤트 보내기를 클릭하여 스토리지 버킷과의 연결을 확인하세요. 이 테스트 이벤트는 통합이 데이터를 올바르게 수신하고 처리할 수 있는지 검증합니다.
테스트 이벤트 데이터 형식: 테스트 이벤트에는 각 필드에 맞는 데이터 유형의 입력 안내 값이 포함되지만, 실제와 같거나 정확한 데이터는 포함되지 않습니다. 예를 들어 timezone 필드에는 유효한 시간대 식별자(예: “America/Chicago”) 대신 UUID와 비슷한 문자열이 들어 있을 수 있으며, campaign_name 및 ip_pool 같은 다른 필드에도 실제 데이터가 아닌 입력 안내 값이 들어 있을 수 있습니다.
이는 정상적인 동작입니다. 테스트 이벤트는 주로 연결 및 통합 설정을 테스트하기 위한 것이며, 데이터 정확성을 검증하기 위한 것이 아닙니다. 정확한 데이터가 담긴 실제 이벤트를 확인하려면 테스트용 Currents 통합을 사용하여 파이프라인을 통해 실제 이벤트 데이터를 전송하세요.
최소 한 번 전송
Currents는 처리량이 많은 시스템이므로 이벤트를 ‘최소 한 번(at-least-once)’ 전송합니다. 즉, 스토리지 버킷에 중복 이벤트가 기록되는 경우가 가끔 있을 수 있습니다. 이는 어떤 이유로든 대기줄에서 이벤트가 다시 처리될 때 발생할 수 있습니다.
사용 사례에 ‘정확히 한 번(exactly-once)’ 전송이 필요하다면, 모든 이벤트와 함께 전송되는 고유 식별자 필드(id)를 사용하여 이벤트의 중복을 제거할 수 있습니다. 파일이 스토리지 버킷에 기록되는 시점부터는 Braze의 관리 범위를 벗어나므로, Braze 측에서 중복 제거를 보장할 방법이 없습니다.
타임스탬프
Currents에서 내보내는 모든 타임스탬프는 UTC 시간대로 전송됩니다. 일부 이벤트에서는 사용 가능한 경우 시간대 필드도 함께 포함되며, 이 필드는 이벤트 발생 당시 사용자의 현지 시간대를 IANA(Internet Assigned Numbers Authority) 형식으로 제공합니다.
지연 시간
SDK 또는 API를 통해 Braze로 전송되는 이벤트에는 과거 시점의 타임스탬프가 포함될 수 있습니다. 가장 대표적인 예는 모바일 연결이 없을 때처럼 SDK 데이터가 대기열에 쌓이는 경우입니다. 이 경우 이벤트 타임스탬프는 이벤트가 생성된 시점을 반영합니다. 따라서 일부 이벤트는 지연 시간이 길게 나타날 수 있습니다.
Braze Android, Swift 및 웹 SDK는 전송되지 않은 이벤트를 기기에 저장하고, 기기가 다시 연결되면 시간 제한 없이 재시도합니다. 웹 SDK의 경우 대기 중인 이벤트는 브라우저 저장 공간(약 5 MB)에 의해서만 제한됩니다.
늦게 도착하는 이벤트에 대한 최대 기간은 없습니다. Currents는 이벤트 타임스탬프가 얼마나 오래되었는지와 관계없이 수신한 모든 이벤트를 내보내도록 설계되었습니다. 늦게 도착한 이벤트는 Braze에서 처리 대기열에 들어간 시간에 해당하는 date= 파티션에 기록되며, time 필드에는 원래 타임스탬프가 유지됩니다. Braze는 늦게 도착한 이벤트를 이전 파티션에 백필하지 않습니다.
늦게 도착한 이벤트는 현재 파티션에 기록되므로, Braze는 룩백 기간을 두고 이전 date= 파티션을 다시 스캔하는 대신 스토리지 버킷에 파일이 기록되는 대로 처리할 것을 권장합니다. 중복을 제거하려면 최소 1회 전송에 설명된 대로 이벤트 id 필드를 사용하세요.
Apache Avro 형식
Braze Currents 데이터 스토리지 통합은 데이터를 .avro 형식으로 출력합니다. Braze가 Apache Avro를 선택한 이유는 스키마 진화를 기본적으로 지원하는 유연한 데이터 형식이며, 다양한 데이터 제품에서 지원되기 때문입니다.
- Avro는 거의 모든 주요 데이터 웨어하우스에서 지원됩니다.
- 데이터를 S3에 그대로 두려는 경우, Avro는 CSV나 JSON보다 압축률이 높아 스토리지 비용을 줄일 수 있고 데이터 구문 분석에 필요한 CPU 사용량도 줄일 수 있습니다.
- Avro는 데이터를 쓰거나 읽을 때 스키마가 필요합니다. 스키마는 시간이 지나면서 진화할 수 있으므로, 기존 동작을 깨뜨리지 않고 필드를 추가할 수 있습니다.
Currents는 다음 형식을 사용하여 이벤트 유형별로 파일을 생성합니다.
<your-bucket-prefix>/dataexport.<cluster-identifier>.<connection-type-identifier>.integration.<integration-id>/event_type=<event-type>/date=<date>/version=<currents_version>/<environment>/dataexport.<cluster-identifier>.<connection-type-identifier>.integration.<integration-id>+<partition>+<offset>.avro
예를 들어 푸시 전송 이벤트 경로는 다음과 같을 수 있습니다.
currents-export/dataexport.prod-01.S3.integration.69cadaaed2d51b7c75b1a3e5/event_type=users.messages.pushnotification.Send/date=2025-04-01-17/version=6/us-01/dataexport.prod-01.S3.integration.69cadaaed2d51b7c75b1a3e5+0+123456.avro
version 경로 세그먼트는 version=6과 같은 단순한 정수 형태의 Currents 버전 값입니다.
version 경로 세그먼트는 파일의 스키마가 변경되었음을 나타냅니다. 이 값은 지표로만 사용하고, 쿼리하는 데이터 열로 사용하지 마세요.
일부 도구는 version=6과 같은 Hive 스타일 key=value 경로 세그먼트를 파티션 열로 읽습니다(예: Hive 파티셔닝을 사용하는 BigQuery 외부 테이블). 이 방식으로 파일을 로드하면 version 파티션 키가 users.messages.inappmessage.Abort 이벤트의 version 필드처럼 이름이 같은 version 이벤트 필드와 충돌할 수 있습니다.
이 충돌을 방지하려면 version 경로 세그먼트를 열로 취급하지 않도록 파이프라인을 설정하세요. 인앱 메시지의 version 필드 값은 무시해도 됩니다. 이 필드는 현재는 더 이상 사용되지 않는 레거시 인앱 메시지와 트리거된 인앱 메시지를 구분하던 레거시 필드입니다.
| 파일 이름 세그먼트 | 정의 |
|---|---|
<your-bucket-prefix> |
이 Currents 통합에 설정된 접두사입니다. |
<cluster-identifier> |
Braze 내부용입니다. “prod-01”, “prod-02”, “prod-03”, “prod-04”와 같은 문자열입니다. 모든 파일의 클러스터 식별자는 동일합니다. |
<connection-type-identifier> |
연결 유형의 식별자입니다. 옵션은 “S3”, “AzureBlob”, “GCS”입니다. |
<integration-id> |
이 Currents 통합의 고유 ID입니다. Braze는 통합을 생성할 때 이 ID를 설정하며, 필드 변환과 같은 통합 설정을 편집해도 변경되지 않습니다. |
<event-type> |
파일에 포함된 이벤트 유형입니다. |
<date> |
이벤트가 처리를 위해 시스템 대기줄에 추가된 시간(UTC 시간대 기준)입니다. YYYY-MM-DD-HH 형식입니다. |
version=<currents_version> |
파이프라인 경로의 Currents 버전입니다. 이 값은 6과 같은 단순한 정수입니다. |
<environment> |
Braze 내부용입니다. |
<partition> |
Braze 내부용입니다. 정수입니다. |
<offset> |
Braze 내부용입니다. 정수입니다. 같은 시간 내에 전송된 파일이라도 <offset> 파라미터는 서로 다릅니다. |
파일 명명 규칙은 변경될 수 있습니다. Braze는 버킷에서 <your-bucket-prefix> 접두사가 있는 모든 키를 검색할 것을 권장합니다.
Avro 쓰기 임계값
일반적인 상황에서 Braze는 5분 또는 15,000개 이벤트 중 먼저 도달하는 시점마다 스토리지 버킷에 데이터 파일을 씁니다. 부하가 높을 때는 파일당 최대 100,000개 이벤트가 포함된 더 큰 데이터 파일을 쓸 수 있습니다.
Currents는 수백만 명의 사용자에게 전송된 메시지에서 발생하는 이벤트처럼 대량으로 몰리는 이벤트를 내부적으로 버퍼링하도록 설계되었습니다. 이러한 급증에 대비해 스토리지 버킷의 쓰기 처리량이나 I/O 용량을 추가로 계획할 필요가 없습니다.
Currents는 빈 파일을 쓰지 않습니다.
Avro 스키마 변경 사항
Braze는 필드가 추가, 변경 또는 제거될 때 가끔 Avro 스키마를 변경할 수 있습니다. 여기서는 변경 사항을 호환성이 깨지는 변경과 호환성이 유지되는 변경의 두 가지 유형으로 구분합니다. 모든 스키마 변경 사항은 Currents 릴리스에 포함되며, 각 릴리스마다 스토리지 경로의 version=<currents_version> 세그먼트가 올라갑니다(예: version=6에서 version=7로). Azure Blob Storage, Google Cloud Storage, Amazon S3에 기록되는 Currents 이벤트는 다음 경로 형식을 사용합니다.
<your-bucket-prefix>/<currents-integration-id>/event_type=<event-type>/date=<date>/version=<currents_version>/<environment>/<avro-file>
호환성이 유지되는 변경 사항
Avro 스키마에 필드가 추가되는 경우 호환성이 유지되는 변경으로 간주합니다. 추가된 필드는 항상 “선택적” Avro 필드(예: 기본값이 null인 필드)이므로 Avro 스키마 해석 사양에 따라 이전 스키마와 “일치”합니다. 이러한 추가 사항은 기존 추출, 변환, 로드(ETL) 프로세스에 영향을 주지 않습니다. 해당 필드는 ETL 프로세스에 추가될 때까지 단순히 무시되기 때문입니다.
새 필드가 추가될 때 흐름이 깨지지 않도록 ETL 설정에서 처리할 필드를 명시적으로 지정하는 것이 좋습니다.
호환성이 깨지는 변경 사항
Avro 스키마에서 필드가 제거되거나 변경되는 경우 호환성이 깨지는 변경으로 간주합니다. 사용 중이던 필드가 더 이상 예상대로 기록되지 않을 수 있으므로, 호환성이 깨지는 변경 사항이 있으면 기존 ETL 프로세스를 수정해야 할 수 있습니다.
호환성이 깨지는 모든 변경 사항은 릴리스 전에 미리 안내됩니다.
버전별 전체 변경 내역은 Currents 체인지로그를 참조하세요.