llm-wiki/raw/company-tech-blogs/outbox-confluent-kafka-connect-smt.md

---
title: Confluent — Kafka Connect Single Message Transforms (SMT) for Outbox Pattern
source_type: company-tech-blog
url: https://www.confluent.io/blog/kafka-connect-single-message-transformation-tutorial-with-examples/
archive_url:
status: needs-confirmation
confidence: medium
tags: [ca-outbox-pattern, confluent, kafka-connect, smt, cdc, company-case-study]
related_branches: [feature-domain-event-outbox-contract, feature-background-job-async-contract]
related_projects: [ca-skeleton-operational-contract]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# Confluent — Kafka Connect SMT for Outbox Pattern

> Layer: `raw/company-tech-blogs/` — Confluent 블로그 "Kafka Connect Deep Dive – Single Message Transforms" 의 SMT 정의/한계 발췌. ca-tmpl outbox 6대안 중 **대안 2 (Kafka Connect SMT 기반 outbox)** 의 사례.
>
> **출처 신뢰도 경고**: company-tech-blog. 공식 best practice 로 취급 금지 — 특정 벤더(Confluent)의 사례·관점일 뿐. SMT 가 outbox 의 표준 해법이라는 일반화는 금지.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-domain-event-outbox-contract]] | outbox 6대안 비교에서 "Kafka Connect SMT" 대안의 정의·한계 근거 (light-weight 변환에만 적합, 복잡 enrichment 는 stream processor 필요) |
| [[raw/branch-notes/feature-background-job-async-contract]] | outbox → topic 매핑을 application 코드 polling 으로 할지 vs Kafka Connect SMT 변환 layer 로 할지의 분기 근거 |

특정 branch 없이 foundational 조사로 수집한 경우:

- [[raw/project-notes/ca-skeleton-operational-contract]] — Contract #19 의 Domain Event / Outbox 항목에서 Confluent 스택 채택 안 함의 trade-off 근거 자료

## 컨텍스트 / 왜 저장했는지

ca-tmpl 의 SKIP LOCKED 결정에 대한 **대안 2: Kafka Connect 의 outbox SMT 를 이용한 변형**. Debezium 과 유사하지만 connector 선택지가 다르고, Confluent 가 권장하는 production pattern 확인용. 단 SMT 는 light-weight 변환에 한정됨을 본 자료가 직접 명시.

## 출처 / Source

- 원본 URL: https://www.confluent.io/blog/kafka-connect-single-message-transformation-tutorial-with-examples/
- 아카이브 URL: (미수집)
- 저자 / 조직: Confluent
- 발행일: rolling (Confluent blog)
- 마지막 확인일: 2026-05-27
- 보조 참고 (404 — 페이지 제거됨, 직접 검증 불가):
  - `https://www.confluent.io/blog/messaging-microservices-mongodb-transactional-outbox/` — MongoDB transactional outbox (현재 404)
  - `https://www.confluent.io/blog/event-driven-microservices-with-apache-kafka-the-transactional-outbox-pattern/` — outbox pattern (현재 404)

## 핵심 인용 / Key quotes (verbatim)

> [§SMT 정의] "Single Message Transforms (SMTs), and as the name suggests, it operates on every single message in your data pipeline as it passes through the Kafka Connect connector."

> [§SMT 동작 위치] "Source connectors pass records through the transformation before writing to the Kafka topic, and sink connectors pass records through the transformation before writing to the sink."

> [§Common uses] "Some common uses for transforms are: Renaming fields, Masking values, Routing records to topics based on a value, Converting or inserting timestamps into the record, Manipulating keys."

> [§한계 — 명시적 경고] "Transforms are a powerful concept, but they should only be used for simple, limited mutations of the data. Don't call out to external APIs or store state, and don't attempt any heavy processing."

> [§한계 — stream processor 권고] "Heavier transforms and data integrations should be handled in the stream processing layer between connectors using a stream processing solution such as Kafka Streams or KSQL."

> [§한계 — split/join 불가] "Transforms cannot split one message into many, nor can they join other streams for enrichment or do any kinds of aggregations. Such activities should be left to stream processors."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| OUTBOX-CFL-C1 | SMT 는 Kafka Connect connector 를 통과하는 모든 single message 에 동작하는 변환 메커니즘 | [§SMT 정의] "Single Message Transforms (SMTs)... operates on every single message in your data pipeline as it passes through the Kafka Connect connector." | `company-case-study` | Kafka Connect 기반 데이터 파이프라인의 message-level 변환 layer | "SMT 가 outbox 패턴의 표준 구현" 이라는 뜻은 아님 — 본 인용은 SMT 일반 정의 |
| OUTBOX-CFL-C2 | SMT 는 source connector 에서 Kafka topic 쓰기 전, sink connector 에서 sink 쓰기 전 적용된다 (양방향 hook 지점) | [§SMT 동작 위치] "Source connectors pass records through the transformation before writing to the Kafka topic, and sink connectors pass records through the transformation before writing to the sink." | `company-case-study` | Kafka Connect 의 source/sink connector 양쪽에서의 변환 시점 | "outbox row 를 topic 으로 변환하는 SMT 의 구체 예제" 본 인용에 미포함 |
| OUTBOX-CFL-C3 | SMT 의 일반적 용도: 필드 rename, 값 masking, value 기반 topic routing, timestamp 변환/삽입, key 조작 | [§Common uses] "Renaming fields, Masking values, Routing records to topics based on a value, Converting or inserting timestamps into the record, Manipulating keys." | `company-case-study` | SMT 의 적합 use case 카탈로그 | "outbox aggregate_type → topic name routing" 이 SMT 의 공식 예제라는 뜻은 아님 — 본 인용은 일반 카탈로그 |
| OUTBOX-CFL-C4 | SMT 는 simple/limited mutation 에만 사용해야 한다 — external API 호출, state 저장, heavy processing 금지 (벤더 명시 경고) | [§한계 — 명시적 경고] "Transforms are a powerful concept, but they should only be used for simple, limited mutations of the data. Don't call out to external APIs or store state, and don't attempt any heavy processing." | `company-case-study` | SMT 의 설계 한계 (Confluent 자체 권고) | "outbox 패턴이 SMT 만으로 완결된다" 는 뜻은 아님 — enrichment 필요 시 별도 stream processor 필수 |
| OUTBOX-CFL-C5 | Heavier transform / data integration 은 Kafka Streams 또는 KSQL 같은 stream processing layer 에서 처리해야 한다 (Confluent 권고) | [§한계 — stream processor 권고] "Heavier transforms and data integrations should be handled in the stream processing layer between connectors using a stream processing solution such as Kafka Streams or KSQL." | `company-case-study` | Confluent 스택 내 책임 분리 — SMT vs stream processor | "stream processor 없이 outbox 가 동작 불가" 는 아님 — 단순 변환은 SMT 로 충분 |
| OUTBOX-CFL-C6 | SMT 는 1 message → N messages split 불가, stream join 불가, aggregation 불가 (구조적 제약) | [§한계 — split/join 불가] "Transforms cannot split one message into many, nor can they join other streams for enrichment or do any kinds of aggregations." | `company-case-study` | SMT 의 구조적 한계 | outbox 의 1 row → 1 event 매핑이 항상 가능하다는 뜻은 아님 — 도메인에 따라 1:N 필요 시 SMT 부적합 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `OUTBOX-CFL-C1` ~ `C3`: Kafka Connect SMT 의 정의·동작 위치·일반 use case
  - `OUTBOX-CFL-C4` ~ `C6`: SMT 의 명시적 한계 (Confluent 자체가 stream processor 와 책임 분리 권고)
- **이 자료가 증명하지 않는 것**:
  - "outbox 패턴 = Kafka Connect SMT" 라는 등치 (본 페이지는 SMT 의 일반 튜토리얼, outbox 전용 가이드 아님)
  - dual-write 문제의 정의 (본 인용은 SMT 한정)
  - MongoDB / Postgres outbox 구체 구현 (보조 URL 404)
  - Confluent Platform 의 EOS (exactly-once semantics) 보장 메커니즘
  - SMT 가 application polling 보다 운영 비용이 낮다는 일반화
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl 의 outbox row 변환이 simple mutation 범위인지 (`OUTBOX-CFL-C4` 기준)
  - Kafka Connect cluster 운영 인력/지식 (Schema Registry 포함)
  - aggregate_type → topic routing 패턴의 SMT 구체 config (`io.debezium.transforms.outbox.EventRouter` 별도 확인 필요)
  - Confluent Cloud 라이선스/비용 vs self-hosted Kafka Connect 비용 비교

## 메모 / Notes (내 프로젝트 해석)

> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

- 적용 시나리오: Confluent Cloud / Confluent Platform 사용 조직, Debezium 외 다른 source connector(MongoDB Source Connector 등) 를 쓰는 경우.
- 장점:
  - Kafka 생태계 안에서 outbox → topic 매핑이 깔끔 (`OUTBOX-CFL-C2` 의 hook 지점 활용)
  - SMT 가 표준화돼 있어 connector 변경 시에도 변환 로직 재사용
  - Schema Registry / Avro 같은 Confluent 스택과 자연스럽게 결합
- 단점:
  - Confluent / Kafka Connect 종속도 증가
  - SMT 는 light-weight 변환용 (`OUTBOX-CFL-C4` 벤더 명시). 복잡한 enrichment 는 별도 stream processor (ksqlDB / Kafka Streams) 필요 (`OUTBOX-CFL-C5`)
  - 라이센스 / 비용 (Confluent Platform 일부 기능)
- ca-tmpl(SKIP LOCKED polling) 과의 차이:
  - Debezium 케이스와 사실상 동일한 trade-off (CDC 기반, polling 제거)
  - 추가로 Confluent 스택에 더 깊이 결합됨
- 운영 복잡도: 중상. Kafka Connect + Schema Registry 운영 부담.
- exactly-once / at-least-once 보장 수준: **at-least-once** 기본 (본 인용에 미명시 — 별도 확인 필요). Kafka transactions / idempotent producer 조합으로 EOS 시도 가능하나 outbox + SMT end-to-end EOS 는 별도 검증 필요.
- 외부 의존성 추가 여부: Kafka, Kafka Connect, (Schema Registry).
- 출처 신뢰도 재확인: 보조 URL 두 개가 404 (Confluent 페이지 제거). 인용 가능한 것은 SMT 튜토리얼 본문만 — 따라서 "Confluent 가 outbox 를 권장한다" 는 진술 자체가 본 자료로 증명 안 됨. **needs-confirmation** 유지.

## Related / 관련

- 같은 주제 다른 raw 자료:
  - [[raw/official-docs/event-sourcing-vs-outbox-microservices-io]] (대안 4: event sourcing)
  - [[raw/company-tech-blogs/outbox-netflix-domain-events-cdc]] (대안 6: Netflix DBLog)
  - [[raw/company-tech-blogs/outbox-wix-engineering-debezium]] (대안 1 사례: Wix Debezium)
  - [[raw/company-tech-blogs/domain-event-sourcing-vs-cqrs-greg-young]] (event/CQRS 정의 정리)
- 인용하는 branch:
  - [[raw/branch-notes/feature-domain-event-outbox-contract]]
  - [[raw/branch-notes/feature-background-job-async-contract]]
- 인용하는 wiki: (미작성)