Importer Design의 원칙
보안
- 업로드된 파일은 유효성을 검사해야 합니다. 예시:
로깅
- 로그에는
github
,bitbucket
,bitbucket_server
와 같은 Importer 유형이 포함되어야 합니다. 전체 Import 소스 목록은Gitlab::ImportSources
에서 확인할 수 있습니다. - 디버깅에 도움이 될 만한 정보를 포함해야 합니다:
-
id
,iid
와 같은 객체 식별자 및 객체 유형 - 오류 또는 상태 메시지
-
- 사용자 이름, 이메일 주소 등을 포함하여 민감하거나 개인적인 정보는 로그에 포함해서는 안 됩니다.
- 적용 가능한 경우, UI에서 오류를 표시하는 데 도움이 되도록
Gitlab::Import::ImportFailureService
에서 오류를 추적해야 합니다. - 로깅은 키 식별자가 누락된 경우 개발 환경에서 오류를 발생시켜야 하며, 이에 대한 데모는 이 MR에서 확인할 수 있습니다.
- 각 레코드가 가져오기 전후에 로그 라인을 작성해야 하며, 해당 레코드의 식별자를 포함해야 합니다.
성능
- 24시간의 기본 TTL이 있는 캐시를 사용하여 중복 데이터베이스 쿼리 및 API 호출을 방지해야 합니다.
- 컬렉션을 순회하는 Worker는 중단되었을 때 이어서 진행할 수 있는 진행 포인터를 갖추어야 합니다.
- 쓰기 중심의 Worker는 데이터베이스를 포화시키지 않도록
defer_on_database_health_signal
을 구현해야 합니다. 그러나 작성 시점에서는 알려진 이슈로 인해 사용할 수 없습니다. - 리소스 포화를 피하도록 Worker 동시성에 제한을 부과해야 합니다. 이에 대한 예시는 Bitbucket의
ParallelScheduling
클래스에서 찾을 수 있습니다. - 새로운 기능을 구현하거나 기능 플래그를 활성화하는 경우에는, 가져오기 작업을 위한 스테이징 환경에서 규모별 테스트를 수행해야 합니다.
탄력성
- Worker는 이상적으로 임파던트여야 하므로 실패한 경우에 안전하게 재시도할 수 있어야 합니다.
- Worker는 동시 일괄 처리 제한을 준수하는 지연 시간으로 다시 대기열에 들어가야 합니다.
- 개별 Worker는 오랜 시간 실행해서는 안 됩니다. 오랜 시간 실행되는 Worker는 배포로 인해 Sidekiq에 의해 중단될 수 있거나
StuckProjectImportJobsWorker
에 의해 중단된 가져오기의 일부로 오인식될 수 있습니다.- Worker가 오래 실행되야 하는 경우에는
StuckProjectImportJobsWorker
에 의해 종료되지 않도록Gitlab::Import::RefreshImportJidWorker
를 사용하여 JID를 새로 고칠 수 있어야 합니다. 또한 Sidekiqmax_retries_after_interruption
를 늘려야 할 수도 있습니다. GitHub Importer 구현을 참조하세요.
- Worker가 오래 실행되야 하는 경우에는
- 캐시된 값에 의존하는 Worker는 캐시 miss 시 데이터를 가져오기 위한 후속 메커니즘을 구현해야 합니다.
- 가능하고 효율적인 경우 데이터를 재획득하세요.
- 누락된 값에 대해 적절하게 처리하세요.
- 오랜 시간 실행되는 Worker는
worker_resource_boundary :memory
를 포함하여 메모리에 배치하여 두 시간의 종료 우선 순위를 부여해야 합니다. 긴 종료 우선 순위는 빠른 Worker 작성을 대체하는 것이 아닙니다. Apdex SLO 준수는 I&I팀 Grafana 대시보드에서 모니터링될 수 있습니다. - 데이터를 생성하는 Worker는 개별 레코드의 실패로 전체 가져오기를 실패시키지 않아야 합니다. 적절한 오류를 기록하고 오류의 성격에 따라 재시도를 결정해야 합니다.
- 가져오기 Stage Worker(포함하여
StageMethods
) 및 Advance Stage Worker(포함하여Gitlab::Import::AdvanceStage
)는 시스템 중단에 대한 내성을 높이기 위해retries: 6
를 가져야 합니다. 지수적 백오프를 사용하면 약 20분에 걸쳐 여섯 번의 재시도가 이루어집니다. 더 높은 재시도 횟수는 가져오기를 너무 오랜 시간 동안 중단시킵니다. - 가져오기의 일부를 재시도할 수 있어야 합니다. 예를 들어, 전체 대상 프로젝트를 덮어쓰지 않고 누락된 이슈를 다시 가져올 수 있어야 합니다.
일관성
- 레코드를 저장한 후에 콜백을 실행해야 합니다. 문제가 있는 콜백은 개별적으로 가져오기에 대해 비활성화될 수 있습니다:
-
Importable
모듈을 포함하세요. -
importing?
일 경우 콜백을 건너뛰도록 콜백을 구성하세요. - 가져올 객체에서
importing
값을 설정하세요.
-
- 레코드를 일괄로 삽입해야 하는 경우 수동으로 콜백을 실행하세요.