> ## Documentation Index
> Fetch the complete documentation index at: https://control.datarelay.run/llms.txt
> Use this file to discover all available pages before exploring further.

# S3·MinIO 버킷 로그 수집

> S3 Object Polling, Prefix/패턴 필터, Stream 및 Destination 전송을 실습합니다.

# AWS S3 또는 MinIO 로그 파일 수집하기

**목표:** S3 호환 버킷의 가상 이벤트 파일을 수집하고 Stream/Route를 통해 전송합니다.

> [!NOTE]
>
> **화면 버전:** 표시된 이미지는 과거 Control UI 테스트 캡처입니다. 현재 제품의 기본 5단계 순서(Connect → Sample & Record Selection → Destinations → Route Processing → Deploy)를 우선하세요. [번호별 화면 가이드](https://control.datarelay.run/ko/use-cases/screen-walkthrough.md)에서 차이를 설명합니다.

## 실행 순서와 완료 기준

1. **필수 정보 준비:** Vendor 공식 API/연동 가이드에서 Endpoint, 인증 방식, 최소 권한, Pagination/Checkpoint, 응답 샘플을 확인합니다. 테스트용 비식별 이벤트와 실제 Destination 접속 정보를 준비합니다.
2. **모르는 항목은 ChatGPT로 정리:** 공개 API 문서와 비식별 샘플을 제공하고 Connector 필수 필드, 요청 예시, Event Root, Timestamp/ID, Cursor, 미확인 사항을 표로 요청합니다. **Token·비밀번호는 입력하지 않습니다.** ChatGPT 답변은 Vendor 문서와 Run Test로 검증합니다.
3. **Connector 생성:** Connectors → Create Connector에서 이 페이지의 해당 Source Type을 선택하고 실제 접속·인증 정보를 입력합니다. 저장하고 연결 테스트를 확인합니다.
4. **Destination 생성:** Destinations → Create에서 실제 수신기 유형(SYSLOG\_UDP/TCP/TLS 또는 WEBHOOK\_POST)을 선택하고 Host/Port/URL, TLS/인증을 입력합니다.
5. **Stream 생성:** Streams → Create → Connect에서 Connector를 선택하고 Source 요청/수집 조건을 지정합니다.
6. **샘플과 스키마:** Sample & Record Selection → Run Test에서 실제 레코드가 추출되는지 확인합니다. Record Root, Union Schema, Pagination 및 Checkpoint를 확정합니다.
7. **데이터 처리:** Destinations에서 Route를 연결하고 Route Processing에서 Mapping, Timestamp, Enrichment, Masking/Drop/Quarantine을 설정합니다. Tokenization은 **실제 제품에서 지원되는 경우에만** 사용합니다. Route Effective Status와 최종 출력값을 확인합니다.
8. **배포와 검증:** Deploy의 경고를 해결하고 Stream을 실행합니다. Run ID, Route Logs와 **실제 Destination 수신 기록**을 비교합니다. 이 세 가지가 일치해야 완료입니다.
9. **장애 대응:** 연결/인증 오류는 API 권한·TLS·Network·429를, 레코드 0건은 Record Root·Pagination을, 전송 실패는 [Delivery Incident](https://control.datarelay.run/ko/use-cases/delivery-incident.md)를, 필드 변경은 [Schema Drift](https://control.datarelay.run/ko/use-cases/schema-change.md)를 확인합니다.

### ChatGPT 질문 예시

> DataRelay Control에서 이 제품의 로그를 수집하려고 합니다. 아래 공개 API 가이드와 비식별 JSON 샘플을 기준으로 Connector 연결·인증 필수값, API Request/Pagination, Event Root, Timestamp/ID/Checkpoint, Mapping·민감 필드 보호, 장애 시 확인 항목을 표로 작성해 주세요. 문서에 없는 정보는 임의로 생성하지 말고 '확인 필요'로 표시하세요.

## 1. 테스트 객체 업로드

테스트용 MinIO 또는 AWS S3 버킷에 `security/tutorial.jsonl` 객체를 만들고 다음 내용을 저장합니다.

```json theme={null}
{"id":"s3-001","message":"object event one","severity":"low"}
```

Control Runtime이 해당 S3 Endpoint에 접근할 수 있어야 합니다. 테스트 권한은 읽기/목록 조회만 부여하고 운영 키를 문서나 Package에 포함하지 않습니다.

## 2. S3 Connector 생성

1. \*\*Connectors → Create Connector → S3 Object Polling (MinIO / AWS-compatible)\*\*을 선택합니다.
2. **Connector Name** = `Lab S3 Events`를 입력합니다.
3. **S3 endpoint & bucket**에서 실제 **Endpoint URL**, **Bucket**, **Region**을 입력합니다.
4. **Prefix** = `security/`, **Object key pattern** = `*.jsonl`을 예시로 설정합니다. 실제 Object Key 구조와 일치하도록 확인합니다.
5. **Access key**, **Secret key**를 Connector의 보호되는 입력 항목에 설정합니다.
6. MinIO는 필요하면 **Path-style addressing**을 켭니다. 보안이 필요한 네트워크에서는 올바른 인증서와 HTTPS를 사용합니다.
7. 저장 후 지원되는 S3 연결/목록 테스트로 지정한 객체가 조회되는지 확인합니다.

## 3. Stream 구성

1. `/streams/new`의 **Connect**에서 `Lab S3 Events`를 선택합니다.
2. **Sample & Record Selection**에서 테스트 후 JSONL 레코드가 올바르게 추출되는지 확인합니다.
3. Event Root와 Union Schema를 점검하고 지원되는 Checkpoint/객체 진행 정책을 구성합니다.
4. [테스트 HTTP Destination](https://control.datarelay.run/ko/use-cases/lab-setup.md)를 선택합니다.
5. **Route Processing → Deploy**를 수행하고 Stream 실행 상태를 확인합니다.
6. **Logs**와 실제 HTTP 수신 파일에서 `s3-001`을 찾습니다.

**완료 조건:** S3 객체 발견, 레코드 추출, Route 전송 성공, 독립 수신 결과가 모두 일치합니다.

![record-selection — numbered Control historical UI capture](https://mintcdn.com/datarelay-control/Tl9_UibGAprPlCr8/images/screenshots/annotated/record-selection.webp?fit=max\&auto=format\&n=Tl9_UibGAprPlCr8\&q=85\&s=196de1ecaf541296095434008afc05ad)

*그림 1. **레코드 경로와 Checkpoint 선택.** ① 추천 Record Path를 검토하고 ② JSON Tree에서 실제 이벤트 필드를 확인한 다음 ③ Checkpoint Field를 지정합니다. 이 화면은 미확정 상태이므로 경고가 표시되어 있습니다.*

![stream-actions — numbered Control historical UI capture](https://mintcdn.com/datarelay-control/Tl9_UibGAprPlCr8/images/screenshots/annotated/stream-actions.webp?fit=max\&auto=format\&n=Tl9_UibGAprPlCr8\&q=85\&s=f5462ebde85e05d0c95ab32096a1a24e)

*그림 2. **Stream 생성 후 실행 및 로그 확인.** ① Stream 생성 결과 확인 → ② 실제 Runtime이 정상일 때 Start Stream → ③ View logs에서 Run과 Route 결과 확인. 캡처에는 Runtime API unavailable이 표시되므로 실제 전송 성공 증거는 아닙니다.*

## 실패 시

* 객체 목록 없음: Bucket/Prefix/Object key pattern/권한 확인
* Endpoint/TLS 실패: Region, URL, 인증서 및 네트워크 확인
* 객체는 읽혔지만 레코드 0건: JSONL/배열/객체 형식과 Record Selection 확인
* 객체 반복 수집: Checkpoint와 객체 식별 처리 확인

**관련:** [첫 이벤트 전송](https://control.datarelay.run/ko/use-cases/webhook-first-flow.md), [Schema 변경](https://control.datarelay.run/ko/use-cases/schema-change.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.