ハウスキーピング

GitLabは、Gitリポジトリでハウスキーピングタスクをサポートし自動化することで、可能な限り効率的にサービスを提供できるようにします。ハウスキーピングタスクには以下が含まれます:

• Gitオブジェクトとリビジョンの圧縮。
• 到達不能なオブジェクトの削除。
• ロックファイルのような古いデータの削除。
• パフォーマンスを向上させるデータ構造の維持。
• オブジェクトプールを更新して、フォーク間のオブジェクト重複排除を改善します。

ハウスキーピング戦略

Gitalyは、Gitリポジトリで2つの方法でハウスキーピングタスクを実行できます:

• 即時ハウスキーピングは、リポジトリの状態とは関係なく、特定のハウスキーピングタスクを実行します。
• ヒューリスティックハウスキーピングは、リポジトリの状態に基づいて、どのハウスキーピングタスクを実行する必要があるかを決定する一連のヒューリスティックに基づいてハウスキーピングタスクを実行します。

即時ハウスキーピング

「即時」ハウスキーピング戦略は、リポジトリの状態とは関係なく、リポジトリ内のハウスキーピングタスクを実行します。これは、手動トリガーとプッシュベースのトリガーで使用されるデフォルトの戦略です。

即時ハウスキーピング戦略は、GitLabアプリケーションによって制御されます。ハウスキーピングジョブの実行をトリガーしたトリガーに応じて、GitLabはGitalyに特定のハウスキーピングタスクの実行をリクエストします。Gitalyは、リポジトリが最適化された状態であっても、これらのタスクを実行します。その結果、この戦略は、ハウスキーピングタスクの実行に時間がかかる大規模なリポジトリでは非効率になる可能性があります。

ヒューリスティックハウスキーピング

ヒューリスティック（または「日和見的」）ハウスキーピング戦略は、リポジトリの状態を分析し、1つ以上のデータ構造が十分に最適化されていない場合にのみハウスキーピングタスクを実行します。これは、スケジュールされたハウスキーピングで使用される戦略です。

ヒューリスティックハウスキーピングは、実行する必要があるタスクを決定するために、次の情報を使用します:

• 無用なオブジェクトと古いオブジェクトの数。
• すでに圧縮されたオブジェクトを含むパックファイルの数。
• 曖昧参照の数。
• コミットグラフの存在。

分析されたデータ構造を最適化する必要があるかどうかの決定は、リポジトリのサイズに基づいています:

• オブジェクトは、すべてのオブジェクトの合計サイズが大きくなるほど頻繁に再パックされます。
• 参照は、合計参照数が多いほど再パックされる頻度が少なくなります。

Gitalyは、これらのデータ構造の最適化には、サイズが大きくなるほど時間がかかるという事実を相殺するためにこれを行います。特に大規模なモノレポ（多くのトラフィックを受信する）では、それらを頻繁に最適化しないことが重要です。

Gitalyにリポジトリの最適化をリクエストする頻度を変更できます。

1. 右上隅で、管理者を選択します。
2. 設定 > リポジトリを選択します。
3. リポジトリの保守を展開します。
4. ハウスキーピングセクションで、ハウスキーピングオプションを設定します。
5. 変更を保存を選択します。

• 自動リポジトリハウスキーピングを有効にする: Gitalyにリポジトリの最適化を定期的に実行するようリクエストします。この設定を長期間無効にすると、GitLabサーバーでのGitリポジトリへのアクセスが遅くなり、リポジトリがより多くのディスク領域を使用するようになります。
• リポジトリの期間を最適化: Gitalyがリポジトリの最適化をリクエストするGitプッシュの数。

ハウスキーピングタスクの実行

GitLabはさまざまな方法でハウスキーピングタスクを実行します:

• プロジェクトの管理者は、リポジトリのハウスキーピングタスクを手動でトリガーできます。
• GitLabは、複数のGitプッシュ後にハウスキーピングタスクを自動的にスケジュールできます。
• GitLabは、設定可能な期間で、すべてのリポジトリのハウスキーピングタスクを実行するジョブをスケジュールできます。

手動トリガー

リポジトリの管理者は、リポジトリ内のハウスキーピングタスクを手動でトリガーできます。一般的に、GitLabはハウスキーピングタスクを自動的に実行するため、これは必要ありません。手動トリガーは、次のいずれかの場合に役立ちます:

• リポジトリがハウスキーピングを必要とすることがわかっている場合。
• ハウスキーピングタスクの自動プッシュベースのスケジューリングが無効になっている場合。

ハウスキーピングタスクを手動でトリガーするには:

1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > 一般を選択します。
3. 高度な設定を展開します。
4. ハウスキーピングを実行を選択します。

これにより、プロジェクトのリポジトリの非同期バックグラウンドワーカーが起動します。バックグラウンドワーカーは、Gitalyにいくつかの最適化を実行するようリクエストします。

ハウスキーピングは、200プッシュごとにプロジェクトから参照されていないLFSファイルも削除し、プロジェクトのストレージ容量を解放します。

到達不能オブジェクトの排除

到達不能オブジェクトは、スケジュールされたハウスキーピングの一部として排除されます。ただし、手動での排除をトリガーすることもできます。ハウスキーピングをトリガーすると、到達不能オブジェクトが2週間の猶予期間で排除されます。到達不能オブジェクトの手動排除をトリガーすると、猶予期間は30分に短縮されます。

到達不能オブジェクトの手動排除をトリガーするには:

1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > 一般を選択します。
3. 高度な設定を展開します。
4. ハウスキーピングを実行を選択します。
5. 操作が完了するまで30分待ちます。
6. ハウスキーピングを実行を選択したページに戻り、到達不能オブジェクトを排除するを選択します。

スケジュールされたハウスキーピング

GitLabはプッシュ数に基づいてハウスキーピングタスクを自動的に実行しますが、まったくプッシュを受信しないリポジトリは維持しません。結果として、休眠中のリポジトリや読み取り専用のリクエストしか受け取らないリポジトリは、リポジトリハウスキーピング戦略の改善の恩恵を受けられない可能性があります。

管理者は、この状況を改善するために、設定可能な間隔ですべてのリポジトリでハウスキーピングを実行するバックグラウンドジョブを有効にできます。このバックグラウンドジョブは、Gitalyノードによってホストされているすべてのリポジトリをランダムな順序で処理し、それらに対してハウスキーピングタスクを熱心に実行します。Gitalyノードは、設定された間隔よりも時間がかかる場合、リポジトリの処理を停止します。

スケジュールされたハウスキーピングの設定

GitリポジトリのバックグラウンドメンテナンスはGitalyで設定されます。デフォルトでは、Gitalyは毎日正午12:00に10分間バックグラウンドリポジトリメンテナンスを実行します。

このデフォルトはGitalyの設定で変更できます。

Gitalyクラスター（Praefect）のある環境では、スケジュールされたハウスキーピングの開始時刻をGitalyノード間でずらすことで、複数のノードでスケジュールされたハウスキーピングが同時に実行されないようにすることができます。

スケジュールされたハウスキーピングの実行が指定されたdurationに達すると、実行中のタスクは正常にキャンセルされます。後続のスケジュールされたハウスキーピングの実行では、Gitalyは処理するリポジトリリストをランダムにシャッフルします。

次のスニペットは、defaultストレージの毎日23:00から1時間のバックグラウンドリポジトリメンテナンスを有効にします:

[daily_maintenance]
start_hour = 23
start_minute = 00
duration = 1h
storages = ["default"]

[daily_maintenance]
disabled = true

gitaly['configuration'] = {
  daily_maintenance: {
    disabled: false,
    start_hour: 23,
    start_minute: 00,
    duration: '1h',
    storages: ['default'],
  },
}

gitaly['configuration'] = {
  daily_maintenance: {
    disabled: true,
  },
}

スケジュールされたハウスキーピングが実行されると、Gitalyログに次のエントリが表示されます:

# When the scheduled housekeeping starts
{"level":"info","msg":"maintenance: daily scheduled","pid":197260,"scheduled":"2023-09-27T13:10:00+13:00","time":"2023-09-27T00:08:31.624Z"}

# When the scheduled housekeeping completes
{"actual_duration":321181874818,"error":null,"level":"info","max_duration":"1h0m0s","msg":"maintenance: daily completed","pid":197260,"time":"2023-09-27T00:15:21.182Z"}

actual_duration（ナノ秒単位）は、スケジュールされたメンテナンスの実行にかかった時間を示します。前の例では、スケジュールされたハウスキーピングは5分強で完了しました。

オブジェクトプールリポジトリ

オブジェクトプールリポジトリは、リポジトリのフォーク間でオブジェクトの重複排除を行うためにGitLabによって使用されます。最初のフォークを作成する際に、次のようにします:

1. フォークされようとしているリポジトリのすべてのオブジェクトを含むオブジェクトプールリポジトリを作成します。
2. Gitの代替メカニズムを使用して、リポジトリをこの新しいオブジェクトプールにリンクします。
3. リポジトリを再パックして、オブジェクトプールからのオブジェクトを使用するようにします。そのため、オブジェクトの独自のコピーを破棄できます。

このリポジトリのフォークは、オブジェクトプールにリンクできるようになり、プライマリリポジトリから分岐するオブジェクトのみを保持すればよいことになります。

GitLabは、オブジェクトプールで特別なハウスキーピング操作を実行する必要があります:

• Gitalyは、到達不能なオブジェクトがそれに接続されているフォークによって使用される可能性があるため、オブジェクトプールから到達不能なオブジェクトを削除することはできません。
• Gitalyは、同じ理由により、すべてのオブジェクトに到達可能にしておく必要があります。したがって、オブジェクトプールは、到達不能な「ぶら下がっている」オブジェクトへの参照を維持し、それらが削除されないようにします。
• GitLabは、プライマリリポジトリに追加された新しいオブジェクトをプルするために、オブジェクトプールを定期的に更新する必要があります。そうしないと、オブジェクトプールはオブジェクトの重複排除においてますます非効率になります。

これらのハウスキーピング操作は、特別なFetchIntoObjectPool RPCによって実行され、これらすべての特別なタスクを処理すると同時に、標準のGitリポジトリに対して実行する通常のハウスキーピングタスクも実行します。

オブジェクトプールは、プライマリメンバーがガベージコレクションされるたびに自動的に最適化されます。そのため、そのプロジェクトでは同じGit GC期間を使用してケイデンスを設定できます。

RailsコンソールからRPCを手動で呼び出す必要がある場合は、project.pool_repository.object_pool.fetchを呼び出すことができます。これは潜在的に長期間実行されるタスクですが、Gitalyは約8時間後にタイムアウトします。