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를 새로 고칠 수 있어야 합니다. 또한 Sidekiq max_retries_after_interruption를 늘려야 할 수도 있습니다. GitHub Importer 구현을 참조하세요.
  • 캐시된 값에 의존하는 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 값을 설정하세요.
  • 레코드를 일괄로 삽입해야 하는 경우 수동으로 콜백을 실행하세요.