컨플루언트(Kafka REST)

Amplitude Data의 Confluent 연동은 Confluent Kafka REST v3 produce API를 사용하여 Amplitude 이벤트 데이터를 Kafka 주제로 스트리밍합니다. 이를 사용하여 자체 커넥터를 실행하지 않고도 Amplitude 이벤트를 Confluent Cloud 또는 자가 관리형 Confluent REST 프록시에 전송할 수 있습니다.

고려 사항

• 이 목적지는 Confluent의 Kafka REST v3 API를 사용합니다. 이 솔루션은 Confluent Cloud와 함께 작동하며 자체 관리형 Confluent REST 프록시 또는 Confluent 서버와 함께 작동합니다. 이 기능은 오래된 v2 경로만 제공하는 Redpanda나 HTTP 프로덕션 API를 전혀 노출하지 않는 Amazon MSK 및 오픈 소스 Apache Kafka에서는 작동하지 않습니다.
• REST 엔드포인트는 공용 인터넷에 연결해야 하며 공용 IP 주소로 확인해야 합니다. Amplitude는 localhost, 내부 전용 호스트 이름 및 개인 주소 범위를 거부하므로 이 목적지를 VPC 내부 프록시 또는 로컬로 호스팅되는 REST 프록시로 가리킬 수 없습니다.
• Amplitude는 Amplitude Export API가 문서화한 것과 동일한 JSON을 레코드 value에 저장합니다.
• Confluent는 거의 실시간으로 스트리밍되는 목적지이므로, 이는 귀하의 이벤트 스트리밍 사용량에 포함됩니다.
• 이 목적지는 Identify Forwarding을 지원합니다. 사용자가 Amplitude에 대해 Identify 호출을 할 때마다 Amplitude는 해당 사용자 정보를 전달합니다. 자세한 내용은 Identify 문서를 참조하십시오.
• Amplitude는 요청당 하나의 레코드를 생성합니다. Confluent는 비스트리밍 produce 모드를 연결당 초당 100개 미만의 요청으로 문서화하므로, 이 목적지로 라우팅할 볼륨을 그에 따라 계획하세요.
• Amplitude는 저장된 상태에서 API 키와 시크릿을 암호화한 후 모든 produce 요청에서 이를 HTTP 기본 인증 자격 증명으로 전송합니다.

연동 설정

Confluent 설정

Amplitude에서 목적지를 생성하기 전에 Confluent Cloud(또는 자체 관리형 클러스터)에서 이러한 단계를 완료하세요.

1. 주제 생성

Amplitude 이벤트를 수신하는 주제를 생성하거나 기존 주제를 선택합니다. Amplitude는 주제를 생성하지 않으므로, 클러스터에 주제 자동 생성이 활성화되어 있지 않은 경우 Amplitude가 첫 번째 이벤트를 전송하기 전에 해당 주제가 존재해야 합니다.

예상되는 볼륨에 따라 파티션 수를 선택하십시오. Amplitude는 모든 이벤트에 레코드 키를 설정하므로 동일한 사용자에 대한 이벤트가 일관되게 동일한 파티션에 도착합니다.

2. 서비스 계정 및 API 키 생성

1. Amplitude를 위한 서비스 계정을 생성하세요.
2. 해당 서비스 계정에 대한 Kafka API 키와 시크릿을 생성하고, 토픽을 호스팅하는 클러스터로 범위를 지정하세요.
3. 비밀을 안전한 곳에 보관하십시오. Confluent는 이를 한 번만 표시합니다.

3. 주제에 대한 쓰기 권한 부여

서비스 계정에 해당 토픽에 대해 메시지를 게시할 수 있는 권한을 부여하세요. Confluent CLI 사용:

confluent kafka acl create \
  --allow \
  --service-account sa-xxxxxx \
  --operations write \
  --topic your-topic-name \
  --cluster lkc-xxxxxx \
  --environment env-xxxxxx

Amplitude는 produce만 수행하므로, write이것이 목적지에 필요한 유일한 작업입니다.

4. 연결 세부 정보 수집

Amplitude에 입력할 다음 값을 수집합니다:

엔드포인트에 API 버전을 포함시킵니다. Confluent Cloud와 Confluent Server는 /kafka/v3를 제공하며, 독립형 REST 프록시는 /v3를 제공합니다. Amplitude는 클러스터 및 주제 경로 세그먼트만 추가합니다.

Amplitude 설정

1. Amplitude 데이터에서 카탈로그를 클릭하고 대상 탭을 선택합니다.
2. 이벤트 스트리밍 섹션에서 **Confluent (Kafka REST)**를 클릭합니다.
3. 동기화 이름을 입력한 다음 동기화 생성을 클릭합니다.
4. 편집을 클릭한 다음 다음을 입력합니다.
   • Kafka REST 엔드포인트: /v3또는 /kafka/v3 접미사를 포함한 Confluent의 엔드포인트입니다.
   • Kafka 클러스터 ID: 예: lkc-xxxxxx.
   • 주제: 이벤트를 수신하는 주제입니다.
   • API 키 및 API 암호: 서비스 계정에 대해 생성한 자격 증명입니다. REST 프록시가 인증 없이 실행되는 경우에만 두 항목을 비워 둡니다.
   • 레코드 키로 사용할 이벤트 필드: 선택 사항입니다. user_id을(를) 사용하려면 이 필드를 비워 둡니다.
5. 이벤트 보내기 필터를 사용하여 전송할 이벤트를 선택합니다. 모든 이벤트를 전송할 수 있지만, Amplitude는 가장 중요한 이벤트를 선택할 것을 권장합니다.
6. 완료되면 목적지를 활성화하고 저장합니다.

레코드 형식

Amplitude는 이벤트당 하나의 생산 요청을 다음 본문과 함께 {endpoint}/clusters/{clusterId}/topics/{topic}/records로 전송합니다:

{
  "key": {"type": "STRING", "data": "user-123"},
  "value": {"type": "JSON", "data": {"user_id": "user-123", "event_type": "Checkout Completed", "...": "..."}}
}

value는 JSON 객체로서의 전체 Amplitude 이벤트이며, Export API 스키마와 일치합니다.

파티셔닝을 key 제어합니다. Amplitude는 'Event field to use'에 명명된 필드를 레코드 키로 사용하거나, 해당 설정이 비어 있는 경우 user_id를 사용합니다. 이벤트에서 선택한 필드가 누락되었거나 비어 있는 경우 Amplitude는 device_id로 되돌아갑니다. 이는 익명 트래픽을 안정적인 파티션에 유지합니다. 두 필드에도 값이 없으면 Amplitude는 키를 생략하고 Confluent는 파티션을 할당합니다.

문제 해결