연동 설정

AI 서비스의 로그 저장소를 연결하고, 파서 코드로 로그를 턴 단위로 바꿔 모니터링(Observability)에 연동합니다.

1. 연동 시작

①연동

연동은 AI 서비스의 사용자 로그를 Datumo Platform으로 가져오는 연결 설정입니다. 애플리케이션마다 지금 쓰는 연동은 하나입니다.

지금은 AWS CloudWatch 로그를 연동합니다.
설정은 두 단계입니다. 1단계에서 접속 정보를 확인하고, 2단계에서 파서 코드를 실행합니다.
설정을 바꾸면 버전이 1씩 올라갑니다. 이전 설정은 연동 이력에 남습니다.

로그 계층과 평가 단위는 모니터링 핵심 개념에서 설명합니다.

②미리 준비할 것

항목	설명
AWS Region	로그가 저장된 지역
액세스 키, 시크릿 키	그 Region에 접근할 수 있는 AWS 키
로그 경로	로그를 불러올 경로(예: `/aws/lambda/my-service`).
파서 코드	로그를 턴으로 나누는 Python 코드

키와 경로는 인프라 담당 팀에 요청합니다.

1-1설정 화면 열기
1. 왼쪽 메뉴 아래 Setting을 클릭합니다.
2. Observability 탭을 클릭합니다.
1-2새 Integration 시작
1. Integration에서 + New Integration을 클릭합니다.
Integration이 없으면 Fail Case 화면에 There are no integrations yet.가 나옵니다.

2. 접속 정보 입력

①Basic Setting 항목

항목	설명
`Region`	로그가 저장된 AWS Region. 목록에서 고릅니다.
`액세스 키` / `시크릿 키`	Region에 접근할 AWS 키. 입력값은 가려집니다.
`로그 경로`	로그를 불러올 경로

②연결 테스트

연결 테스트는 입력한 정보로 실제 연결을 시도합니다. 성공하면 연동된 로그에 불러온 로그가 나옵니다.

가장 최근 로그를 최대 100개까지 불러옵니다.
불러온 로그는 2단계에서 파서 코드 결과를 확인할 때 씁니다.
연결에 성공하면 입력 칸이 잠깁니다.

연결에 실패하면 에러 문구가 나옵니다.

에러	원인	확인할 것
`Invalid access credentials`	키가 틀렸거나 Region 접근 권한이 없음	키 값과 Region 권한
`Log path not found`	입력한 경로가 없음	경로와 표기 방식
`No logs found`	연결은 됐지만 로그가 없음	경로와 조회 기간

2-1접속 정보 입력
1. Region을 고릅니다.
2. Access Key와 Secret Key를 입력합니다.
3. Log Path를 입력합니다.
2-2연결 확인
1. Test Connection을 클릭합니다.
2. Integrated Logs에서 불러온 로그를 확인합니다.
3. Next를 클릭합니다.
네 항목을 모두 입력해야 Test Connection이 켜집니다.
2-3연결 실패 대응
1. 에러 문구를 확인합니다.
2. Set up again을 클릭해 값을 고칩니다.
에러별 원인은 Test Connection에 정리했습니다.

3. 파서 코드 실행

①파서 코드

파서 코드는 원본 로그에서 사용자 질문과 AI 답변을 찾아 턴으로 묶는 Python 코드입니다. 로그 형식은 서비스마다 달라서 직접 작성합니다.

작성 방법은 화면의 파서 가이드 보기에서 확인합니다.
코드는 JSON을 반환해야 합니다.

에러	원인
`Json Format Error`	코드는 실행됐지만 결과가 올바른 JSON이 아닙니다.
`SyntaxError (Compile Error)`	코드 문법이 잘못되어 실행되지 않습니다.
`TypeError (Runtime Error)`	실행 중 맞지 않는 데이터 타입끼리 연산했습니다.

②매핑 미리보기

매핑 미리보기는 파서 결과가 평가용 열에 어떻게 연결되는지 보여 줍니다.

열	뜻
`session_id`	턴이 속한 세션 ID
`turn_id`	턴 ID
`timestamp`	메시지 시각
`type`	`유저 입력` 또는 `앱 출력`
`message`	메시지 내용

필수 값이 빈 행은 빨갛게 표시되고 평가에서 빠집니다.
평가할 수 있는 행이 하나도 없으면 완료가 꺼집니다.
유저 입력과 앱 출력이 번갈아 나오는지 확인합니다. 어긋나면 평가 결과가 잘못 나옵니다.

3-1코드 실행
1. 왼쪽 Integrated Logs에서 원본 로그를 확인합니다.
2. Parser Code (Python)에 코드를 입력합니다.
3. Run을 클릭합니다.
작성 방법은 Check Parser Guide의 Go to Docs에서 확인합니다.
3-2결과 확인
1. Parser Code Output에서 반환한 JSON을 확인합니다.
2. Mapping Preview에서 열 연결을 확인합니다.
3. 빨간 행은 필수 값이 비어 평가에서 빠집니다.
열별 뜻은 Mapping Preview에서 확인합니다.
3-3코드 수정
1. 결과가 다르면 Edit를 클릭합니다.
2. 코드를 고치고 Run을 다시 클릭합니다.
3-4연동 완료
1. Complete를 클릭합니다.
- 완료한 시점과 작업자가 Integration 카드에 기록됩니다.
- 저장하지 않고 창을 닫으면 확인 창이 열립니다.

4. 연동 관리

①연동 정보 카드

항목	뜻
`Integrated at`	마지막으로 `완료`를 누른 시점
`Integrated by`	마지막으로 `완료`를 누른 사람
`latest logged at`	연동된 턴 중 가장 최근 턴의 시점
`total turns`	연동된 전체 턴 수
`수집 설정`	연동 유형, Region, 로그 경로

Integrated at은 설정을 마친 시점입니다. latest logged at은 로그가 실제로 들어온 시점입니다.
설명 칸에 버전 설명을 255자까지 적을 수 있습니다.

②새 연동으로 전환

로그 형식이나 저장 위치가 바뀌면 Switch to new integration으로 새 버전을 만듭니다.

설정 창은 이전 Region, 로그 경로, 파서 코드가 채워진 채로 열립니다.
액세스 키와 시크릿 키는 보안을 위해 비어 있습니다. 다시 입력합니다.
완료하면 버전이 1 올라갑니다. 이전 설정은 연동 이력으로 옮겨집니다.
생성·평가 모델이 없으면 버튼이 꺼집니다.

③연동 해제

연동을 끊으려면 연동 카드 오른쪽 위의 Disconnect를 클릭합니다. 버튼은 Integration History와 Switch to new integration 사이에 있습니다.

Disconnect를 클릭하면 확인 창이 열립니다. 이 단계에서는 아직 해제되지 않습니다.
확인 창에서 Disconnect를 클릭하면 해제됩니다. 처리되는 동안에는 버튼을 누를 수 없습니다.
해제되면 Integration disconnected. 알림이 뜨고, 연동 카드가 There are no integrations. 상태로 바뀝니다.

해제 후	내용
로그 수집	이 연동으로 새 로그를 더 이상 가져오지 않습니다.
다시 연결	해제한 연동은 다시 켤 수 없습니다. `+ New Integration`으로 새로 연동합니다.
지난 결과	해제 전에 평가한 결과는 남습니다.
설정	샘플링 확률과 평가지표 설정은 그대로 유지됩니다.

로그 수집 상태와 상관없이 해제할 수 있습니다.
해제에 실패하면 확인 창이 열린 채로 오류 알림이 나옵니다. 다시 Disconnect를 클릭합니다.

4-1정보 확인
1. Integration 카드에서 버전과 연동 정보를 확인합니다.
2. Ingestion Settings에서 Region과 Log Path를 확인합니다.
항목별 뜻은 Integration 정보 카드에 있습니다.
4-2설명 입력
1. 설명 칸에 이 버전의 설명을 입력하고 Save를 클릭합니다.
4-3이력 확인
1. Integration History를 클릭합니다.
2. 지난 버전의 설정을 최신순으로 확인합니다.
4-4새 버전 만들기
1. Switch to new integration을 클릭합니다.
2. Access Key와 Secret Key를 다시 입력합니다.
3. 2~3단계와 같은 순서로 마칩니다.
이전 설정은 Integration History로 옮겨집니다.
4-5연동 해제
1. Disconnect를 클릭합니다.
2. 확인 창에서 Disconnect를 클릭합니다.
3. 연동 카드가 빈 상태로 바뀐 것을 확인합니다.
해제한 연동은 다시 켤 수 없습니다. + New Integration으로 새로 연동합니다.

자주 묻는 질문

연결 테스트가 왜 눌리지 않나요?입력하지 않은 항목이 있기 때문이에요.

원인: Region, 액세스 키, 시크릿 키, 로그 경로를 모두 넣어야 버튼이 켜져요.
해결 방법: 빈 칸을 채워 주세요.

왜 Invalid access credentials가 나오나요?키가 틀렸거나 Region 접근 권한이 없기 때문이에요.

원인: 유효한 키라도 고른 Region에 접근 권한이 없으면 실패해요.
해결 방법: 키 값과 Region 권한을 인프라 담당 팀과 확인해 주세요.

왜 No logs found가 나오나요?연결은 됐지만 경로에 로그가 없기 때문이에요.

원인: 경로가 비어 있거나 다른 경로일 수 있어요.
해결 방법: 로그 경로와 조회 기간을 다시 확인해 주세요.

파서 단계에서 완료가 왜 눌리지 않나요?평가할 수 있는 행이 없기 때문이에요.

원인: 필수 값이 빈 행은 평가에서 빠져요. 모든 행이 비면 There are no valid rows available for evaluation.가 나와요.
해결 방법: 수정으로 파서 코드를 고치고 다시 실행해 주세요.

Switch to new integration이 왜 눌리지 않나요?생성·평가 모델이 없기 때문이에요.

원인: 등록된 생성·평가 모델이 0개면 버튼이 꺼져요.
해결 방법: Go to Gen & Judge Model Setting에서 모델을 먼저 등록해 주세요.

연결은 되어 있는데 데이터가 보이지 않으면 어떻게 하나요?latest logged at이 갱신되는지 확인해 보세요. 갱신되지 않으면 로그 수집 상태를 점검하면 돼요.

원인: latest logged at은 마지막으로 연동된 턴의 시점이에요.
해결 방법: latest logged at이 갱신되는지 확인해 주세요. 갱신되지 않으면 로그 수집 상태를 점검해 주세요.