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를 새로 고쳐줘야 합니다. 또한 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 값을 설정하세요.
  • 레코드가 대량으로 삽입되어야 하는 경우에는 매뉴얼으로 콜백을 실행하는 것을 고려하세요.