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