• 보안
• 로깅
• 성능
• 복원력
• 일관성

수입자 설계 원칙

보안

• 업로드된 파일은 검증되어야 합니다. 예:
  • BulkImports::FileDownloadService
  • ImportExport::CommandLineUtil

로깅

• 로그는 github, bitbucket, bitbucket_server와 같은 수입자 유형을 포함해야 합니다. 전체 수입 출처 목록은 Gitlab::ImportSources에서 확인할 수 있습니다.

• 로그는 디버깅에 도움이 될 만한 정보를 포함해야 합니다:

  • id, iid와 같은 객체 식별자 및 객체 유형

  • 오류 또는 상태 메시지

• 로그는 사용자 이름, 이메일 주소를 포함한 민감하거나 개인 정보를 포함해서는 안 됩니다.

• 해당되는 경우, UI에서 오류를 표시하는 데 도움이 되도록 Gitlab::Import::ImportFailureService에서 오류를 추적해야 합니다.

• 주요 식별자가 누락되면 개발 중에 오류를 발생시켜야 하며, 이는 이 MR에서 보여줍니다.

• 각 레코드가 가져오기 전후에 해당 레코드의 식별자를 포함하는 로그 라인이 생성되어야 합니다.

성능

• 중복된 데이터베이스 쿼리 및 API 호출을 방지하기 위해 기본 TTL이 24시간인 캐시를 사용해야 합니다.

• 컬렉션을 반복하는 작업자는 중단 시 중단된 위치에서 이어 시작할 수 있도록 진행 포인터를 갖추어야 합니다.

  • ID 추적 예제

  • 페이지 카운터 예제

• 쓰기 집약적인 작업자는 데이터베이스를 포화시키지 않기 위해 defer_on_database_health_signal를 구현해야 합니다. 그러나 작성 당시 알려진 문제가 있어 이를 사용할 수 없습니다.

• 자원을 포화시키지 않도록 작업자 동시성에 대한 제한을 구현해야 합니다. 이를 위해 Bitbucket의 ParallelScheduling 클래스에 대한 예제를 확인할 수 있습니다.

• 새로운 기능을 구현하거나 기능 플래그를 활성화할 때 특히 스테이징 환경에서 수입자를 규모에 맞게 테스트해야 합니다.

복원력

• 작업자는 실패 시 안전하게 재시도할 수 있도록 아이덴포턴트해야 합니다.

• 작업자는 동시 배치 제한을 고려하여 지연하여 재대기되어야 합니다.

• 개별 작업자는 오랫동안 실행되어서는 안 됩니다. 오랜 시간 실행되는 작업자는 배포로 인해 Sidekiq에 의해 중단될 수 있으며, StuckProjectImportJobsWorker에 의해 가져오기가 중단된 것으로 잘못 인식될 수 있습니다.

  • 작업자가 오랫동안 실행되어야 하는 경우, StuckProjectImportJobsWorker에 의해 종료되지 않도록 Gitlab::Import::RefreshImportJidWorker를 사용하여 JID를 새로 고쳐야 합니다. 또한 Sidekiq의 max_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 값을 설정하세요.

• 기록을 대량으로 삽입해야 하는 경우, 콜백을 수동으로 실행하는 것을 고려하세요.